SSO via Open ID Connect

Basics

Our Tech Stack

Data protection

Information security

App Customization & Deployment

Analytics

Project management

Miscellaneous

Languages

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:

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

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

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

1. Click Add a Redirect URI.
2. Under Platform configurations, click Add a platform.
3. Select Web.
4. 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:

1. <android_bundle_id>://login-callback
2. <android_bundle_id>://oidc/login-callback
3. <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

➡️

• 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:

1. Sign in to the Okta account and navigate to the Applications dashboard.
2. Select Create App Integration. The Create a new app integration dialog displays.
3. Configure the following:
1. Sign-in method: Select OIDC - OpenID Connect.
2. Application type: Select Web Application.

4. Select Next. The New Web App Integration page displays.
5. 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:

1. <android_bundle_id>://login-callback
2. <android_bundle_id>://oidc/login-callback
3. <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

➡️

• 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

• Assignments: Select Allow everyone in your organization to access.
6. Select Save. The page displays information for the Sample OIDC App created in the last step and the General tab is active.
7. Note the values in the following fields. You will need them to create the OIDC SSO configuration on the tchop server:
1. Client ID
2. Client secret
3. Okta domain

8. 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

Example of config

Copy { "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

Add content here

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