OpenID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol. It allows tchop to verify the identity of a user based on the authentication performed by an authorization server and obtain basic profile information about the user in an interoperable and REST-like manner. It uses security tokens containing assertions to pass information about a user between the following:

An OIDC identity provider, such as Okta, GSuite, Azure AD or Keycloak
An OIDC service provider, such as the tchop apps for mobile or web

Configuring an Azure Active Directory integration (Now Microsoft Entra ID) (Example)

This section demonstrates how to create an OIDC SSO application integration between Azure Active Directory and your tchop environment. Steps in this section take place on the Azure Active Directory platform. These instructions are for example purposes only and may not reflect the current Azure Active Directory or your identity provider UI. Refer to the your identity provider documentation for instructions.

➡️

You must have an active Azure Active Directory account populated with user names.

To configure the integration for tchop:

Log into your account and click on the Microsoft Entra ID icon.

From the left-side menu, navigate to the App registrations tab and select "New registration."

Create your new app
On the Register an application page, give the application a name.
Set Supported account types to Accounts in this organizational directory only (Default Directory only - Single tenant).
Click Register.
Copy the Application (client) ID and save for later.

Click Add a Redirect URI.
Under Platform configurations, click Add a platform.
Select Web.
Enter the following Redirect URI:

Sign-in redirect URIs:

For WebApp: Enter https://[ORGANISATION].[DOMAIN] /webapp/auth/login. For example: https://meganews.tchop.io/webapp/auth/login

For Mobile Apps:

<android_bundle_id>://login-callback
<android_bundle_id>://oidc/login-callback
<iOS_bundle_id>://login-callback

Sign-out redirect URIs (Only required for Mobile App):

<android_bundle_id>://logout-callback
<android_bundle_id>://oidc/logout-callback
<iOS_bundle_id>://logout-callback

➡️

The client needs to add full list of redirect urls for webApp for all channels:

https://[ORGANISATION].[DOMAIN] /webapp/auth/login
https://[CHANNEL1-ORGANISATION].[DOMAIN] /webapp/auth/login
https://[CHANNEL2-ORGANISATION].[DOMAIN] /webapp/auth/login
https://[CHANNEL3-ORGANISATION].[DOMAIN] /webapp/auth/login
…

⚠️

Please check: Some OIDC providers support wildcard on the redirect url eg https://*.tchop.it/webapp/auth/login, so we don’t need hardcode all possible combination of subdomains. Just add “https://*.tchop.it/webapp/auth/login” to the redirect URL

Click Configure.
Under Manage, select Certificates & secrets.
Click New client secret.
Give the secret a name and set the expiration date to your company's policy (Keep in mind that when this client secret expires, you need to manually update the new value in tchop, we need to renew the client secret or else SSO will not work)

Copy the Value.

➡️

The proper format of the Issuer URL is https://login.microsoftonline.com/{tenant_id}/v2.0. You will find the tenant_id in Azure AD (Microsoft Entra ID) → Default Directory → Overview.

Now, you are ready to create an OIDC service provider on the tchop server. Refer to the section “Creating an OIDC service provider” for details.

Configuring an OKTA integration (Example)

This section demonstrates how to create an OIDC SSO application integration between OKTA and your tchop environment. Steps in this section take place on the Okta platform. These instructions are for example purposes only and may not reflect the current Okta or your identity provider UI. Refer to the your identity provider documentation for instructions.

➡️

You must have an active Okta account populated with user names.

To configure the integration for tchop:

Sign in to the Okta account and navigate to the Applications dashboard.
Select Create App Integration. The Create a new app integration dialog displays.
Configure the following:

Sign-in method: Select OIDC - OpenID Connect.
Application type: Select Web Application.

Select Next. The New Web App Integration page displays.
Enter the following information:

App integration name: Enter <any name>. For example: Sample OIDC App.
Sign-in redirect URIs:

For WebApp: Enter https://[ORGANISATION].[DOMAIN] /webapp/auth/login. For example: https://meganews.tchop.io/webapp/auth/login

For Mobile Apps:

<android_bundle_id>://login-callback
<android_bundle_id>://oidc/login-callback
<iOS_bundle_id>://login-callback

Sign-out redirect URIs (Only required for Mobile App):

<android_bundle_id>://logout-callback
<android_bundle_id>://oidc/logout-callback
<iOS_bundle_id>://logout-callback

➡️

The client needs to add full list of redirect urls for webApp for all channels:

https://[ORGANISATION].[DOMAIN] /webapp/auth/login
https://[CHANNEL1-ORGANISATION].[DOMAIN] /webapp/auth/login
https://[CHANNEL2-ORGANISATION].[DOMAIN] /webapp/auth/login
https://[CHANNEL3-ORGANISATION].[DOMAIN] /webapp/auth/login
…

⚠️

Assignments: Select Allow everyone in your organization to access.

Select Save. The page displays information for the Sample OIDC App created in the last step and the General tab is active.
Note the values in the following fields. You will need them to create the OIDC SSO configuration on the tchop server:

Client ID
Client secret
Okta domain

Select the Assignments tab and assign people to this application.

Now, you are ready to create an OIDC service provider on the tchop. Refer to the section “Creating an OIDC service provider” for details.

Creating an OIDC service provider

➡️

Before creating an OIDC service provider on tchop, you must have an OIDC app integration created with an identity provider such as Okta, GSuite, Azure AD or Keycloak. Refer to the section “Configuring an OKTA integration (Example)” for an example using Okta or “Configuring an Azure Active Directory integration (Now Microsoft Entra ID) (Example)” for an example using Azure AD (Now Microsoft Entra ID)

To use OIDC single sign-on (SSO), you must create an OIDC service provider. In this case, the service provider is tchop. Once you are done creating OIDC SSO application on your identity provider, simply forward us the config. file with the fields mentioned below. Alternatively simply forward us the copied Client ID, Client Secret, Issuer URL values as well as the meta-data URL and we take care of the rest.

➡️

Some fields are available on the "well known" endpoint OpenID Connect defines a discovery mechanism, called OpenID Connect Discovery, where an OpenID server publishes its metadata at a well-known URL, typically

https://<domain>/.well-known/openid-configuration This URL returns a JSON listing of the OpenID/OAuth endpoints, supported scopes and claims, public keys used to sign the tokens, and other details. The clients can use this information to construct a request to the OpenID server eg https://dev-hp8e4p4djxag031s.eu.auth0.com/.well-known/openid-configuration

Required fields for the tchop client

Fields	Description	Example Value
jwksUri	The endpoint will contain the JWK used to verify all issued JWTs for a tenant. The JSON Web Key Set (JWKS) is a set of keys containing the public keys used to verify any JSON Web Token (JWT) issued by the Authorization Server and signed using the RS256 signing algorithm.	http://localhost:9011/.well-known/jwks.json
issuer	Name of tenant	acme.com
algorithm	Signing algorithms are algorithms used to sign tokens issued for your application or API. A signature is part of a JSON Web Token (JWT) and is used to verify that the sender of the token is who it says it is and to ensure that the message wasn't changed along the way. The most secure practice, and our recommendation, is to use RS256	RS256
audience	The audience is the resource/server that the access token is intended for	acme.com
tokenEndpoint	The token endpoint can be used to programmatically request tokens. It must supports the `authorization_code` grant type	http://localhost:9011/oauth2/token
authorizationEndpoint	The authorize endpoint can be used to request tokens or authorization codes via the browser. This process typically involves authentication of the end-user.	http://localhost:9011/oauth2/authorize
userinfoEndpoint	The UserInfo endpoint can be used to retrieve identity information about a user. The caller needs to send a valid access token representing the user. Depending on the granted scopes, the UserInfo endpoint will return the mapped claims (at least the openid scope is required)	http://localhost:9011/oauth2/userinfo
endSessionEndpoint	The end session endpoint can be used to trigger single sign-out	http://localhost:9011/oauth2/logout
clientId	The client identifier that initiated the request	19fe3351-1e6e-4eef-914d-c74e8ebcb010
clientSecret	Required only for confidential web apps. The application secret that you created in the app registration portal for your app. https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow#request-an-access-token-with-a-client_secret	a random string

Example of config

{
  "name": "any human readable name of client",
  "jwksUri": "http://localhost:9011/.well-known/jwks.json",
  "issuer": "acme.com",
  "algorithm": "RS256",
  "authorizationEndpoint": "http://localhost:9011/oauth2/authorize",
  "audience": "acme.com",
  "tokenEndpoint": "http://localhost:9011/oauth2/token",
  "clientId": "19fe3351-1e6e-4eef-914d-c74e8ebcb010",
  "clientSecret": null,
  "userinfoEndpoint": "http://localhost:9011/oauth2/userinfo",
  "endSessionEndpoint": "http://localhost:9011/oauth2/logout"
}

Configuring an Azure Active Directory integration (Now Microsoft Entra ID) (Example)
Configuring an OKTA integration (Example)
Creating an OIDC service provider