Login integration

You can configure Open Authorization (OAuth) 2.0, OpenID Connect (OIDC), or Lightweight Directory Access Protocol (LDAP) for logging on to OceanBase Developer Center (ODC) through single sign-on (SSO).

Background information

Both SSO and LDAP are identity authentication methods, which allow you to securely get authenticated in ODC by using a group of credentials.

Concepts

• OAuth is an open standard authorization protocol that allows users to authorize third-party applications to access their protected information stored on resource services without providing the username or password to the third-party applications. This decouples authentication from authorization. OAuth is a widely recognized and used international standard. OAuth 2.0 is an extension to OAuth 1.0. It is more secure and easier to implement. However, it is incompatible with OAuth 1.0. In other words, OAuth 2.0 deprecates OAuth 1.0. OAuth defines a secure, open, and simple standard for authorizing user resources. A third party can obtain the authorization information of users without the need to obtain the user account and password.

  • OAuth 2.0 is a delegated authorization framework used for REST/APIs.

  • OAuth 2.0 is a token-based authorization protocol that grants applications limited access to user data without disclosing the user password.

  • OAuth 2.0 decouples authentication from authorization.

• OIDC is a security authentication mechanism. A third-party application connects to the identity provider to request user information and the identity provider returns the information to the application in a secure and reliable manner. OIDC extends the OAuth 2.0 protocol. The ID Token field is added to provide basic user identity information. The ID Token field is encapsulated in the JSON Web Token (JWT) format. An ID token encapsulated in the JWT format is self-contained and provides a tamper-proof mechanism. Therefore, it can be securely transferred to a third-party application and easily verified.

• LDAP is an industrial standard protocol used to access and manage directory services. It is generally used to store and retrieve information about users, groups, organizational structures, and other resources in a network environment.

Technical mechanism

OAuth 2.0

ODC adapts to the OAuth 2.0 authentication center and supports only the authorization-code mode. In this mode, applications use an authorization code to request an access token or refresh token from the authorization server.

As shown in the preceding figure, the authorization process comprises the following steps:

1. The user logs on to the application system. The request is forwarded to the authentication server. Then, the logon authentication page appears, with the status code 302 returned.
2. The user enters the account and password for authentication. After authentication, the authentication server returns an authorization code to the application system.
3. The application system sends a request carrying the code to the authentication server to request for an access token. The authentication server verifies the client ID and code and returns an access token to the application system.
4. The application system uses the access token to query the user logon information. The authentication server returns the user information, such as the username.
5. The application system verifies the username, creates a session, and jumps to the redirection URL.

The following table describes the parameters involved in different steps.

OIDC

1. The client sends an authentication request to the authentication service.

2. The user logs on by using the username and password on the authentication page to confirm authorization.

3. The authentication service verifies the authentication request and returns a code to the client.

4. The client requests a callback API from the business service, carrying the code in the request.

5. The business service requests a token from the authentication service, carrying the code, client ID, and client secret in the request.

6. The authentication service verifies the information carried in the request and returns an ID token to the business service.

7. After authentication, the business service returns the ID token to the client.

8. The client initiates a business request, carrying the ID token in the request.

9. The business service verifies the ID token and returns a response to the client.

LDAP

ODC can integrate with an LDAP repository to authenticate users, retrieve user information, and bind user groups. The authorization process is as follows:

1. Configure information about the LDAP identity source in ODC.

2. Choose LDAP logon on the logon page and enter the username and password.

3. The LDAP authentication server verifies the username and password through a BIND request.

4. After successful authentication, the LDAP server returns the user information to ODC.

Prerequisites

• You have the system integration permission.

• You have deployed the authorization service.

Considerations

• Only the authorization-code mode is supported in OAuth and OIDC.

• When you log off in OAuth/OIDC, only the logon state in ODC is cleared, and the logon state in the SSO system is not cleared.

Create a login integration task

Configure SSO based on OAuth 2.0

Example: Use OAuth to integrate Apereo Central Authentication Service (CAS) to ODC so that you can access ODC by using a CAS account.

1. Log on to Web ODC. In the project collaboration window, choose Integrations > Login Integration > Create Login Integration.

   

2. Configure gateway authentication parameters on the Create Login Integration page.

   The following table describes the OAuth parameters.

   Parameter	Description
   Configuration Name	The configuration name will be used as a custom username for logon.
   Type	Select OAUTH2.
   Client ID	The ID of the application, which must be consistent with that registered with the authorization server.
   Auth URL	The URL provided by the authorization server for obtaining the grant code.
   User Info URL	The URL provided by the authorization server for obtaining user information.
   Token URL	The URL provided by the authorization server for obtaining the access token.
   Redirect URL	The callback URL used by the authorization server to call the ODC service. Notice If the SSO system has a callback allowlist, you must add the redirection URL to the allowlist.
   User Data Structure Type	The FLAT and NESTED structure types are supported.
   Scope	The authorization scope. Separate multiple scopes with spaces. We recommend that you set the value to profile. Notice When you configure Alibaba Cloud Object Storage Service (OSS) in a third-party application, the value of Scope must include openid.
   jwkSet URL	Optional. The address of the public key provided by the authorization server for authentication.
   userNameAttribute	Optional. The username.
   Client Authentication Method	The identity authentication method used by the authorization server to authenticate the client.
   Authorization Grant Type	The authorization method of OAUTH2.
   User Info Authentication Method	The identity authentication method used when the access token in the resource request is sent to the resource server.

3. Click Test Connection to go to the CAS logon page.

   Note

   CAS does not require a callback allowlist. If a callback allowlist is required when you integrate another application to ODC, you can manually add an allowlist as prompted.

   

4. Enter the CAS account and password and click Allow on the authorization page to grant access to ODC.

   

5. After the connection test succeeds, the user information API returns structure information. Configure the user field mapping parameters based on the returned information.

   Note

   • The structure returned by a user information API varies based on the third-party application. To map the user information of a third-party application to the user fields in ODC, you must configure the user field mappings. User field mappings identify the ODC account used for OAuth 2.0 logon.
   • You can configure the Username Field and Nickname Field parameters based on the returned connection information.
   • You can also specify custom fields and custom field mapping rules.
   • The system administrator can configure custom field names through automatic authorization. When you log on to ODC by using custom fields, you are automatically granted the specified roles or permissions.

6. Click Save.

7. In the login integration task list, enable the created login integration task.

   Note

   You can enable only one login integration task.

8. On the logon page of Web ODC, click OAUTH2 to go to the third-party logon page and use a third-party account to access ODC.

   

Grant third-party access by using OIDC

Example: Use OIDC to integrate a third-party application to ODC so that you can use a third-party account to access ODC.

1. Log on to Web ODC. In the project collaboration window, choose Integrations > Login Integration > Create Login Integration.

   

2. Configure gateway authentication parameters on the Create Login Integration page.

   The following table describes the OIDC parameters.

   Step	Description
   Configuration Name	The configuration name will be used as a custom username for logon.
   Type	Select OIDC.
   Client ID	The ID of the application, which must be consistent with that registered with the authorization server.
   Client Secret	The secret of the application, which must be consistent with that registered with the authorization server.
   Scope	The authorization scope. Separate multiple scopes with spaces. We recommend that you set the value to profile. Notice When you configure Alibaba Cloud Object Storage Service (OSS) in a third-party application, the value of Scope must include openid.
   Issue URL	The issue address of the authentication service.
   Redirect URL	The callback URL used by the authorization server to call the ODC service. Notice If the SSO system has a callback allowlist, you must add the redirection URL to the allowlist.
   User Data Structure Type	The FLAT and NESTED structure types are supported.

3. An independent callback allowlist is required for connection testing. Manually add an allowlist as prompted and then click Test Connection.

4. Enter the third-party account and password.

5. After the connection test succeeds, the user information API returns structure information. Configure the user field mapping parameters based on the returned information.

   Note

   • The structure returned by a user information API varies based on the third-party application. To map the user information of a third-party application to the user fields in ODC, you must configure the user field mappings. The user field mappings identify the ODC account used for OIDC logon.
   • You can configure the Username Field and Nickname Field parameters based on the returned connection information.
   • You can also specify custom fields and custom field mapping rules.
   • The system administrator can configure custom field names through automatic authorization. When you log on to ODC by using custom fields, you are automatically granted the specified roles or permissions.

6. Click Save.

7. In the login integration task list, enable the created login integration task.

   Note

   You can enable only one login integration task.

8. On the logon page of Web ODC, click OIDC to go to the third-party logon page and use a third-party account to access ODC.

Grant third-party access by using LDAP

Example: Use LDAP to integrate a third-party application to ODC so that you can use a third-party account to access ODC.

1. Log on to Web ODC. In the project collaboration window, choose Integrations > Login Integration > Create Login Integration.

   

2. Configure gateway authentication parameters on the Create Login Integration page.

   The following table describes the LDAP parameters.

   Parameter	Description
   Configuration Name	The configuration name will be used as a custom username for logon.
   Type	Select LDAP.
   URL	The access URL of the LDAP server, which is a formatted string used to define the location and search parameters of the LDAP service.
   User DN	The user domain name for accessing the LDAP server. Each LDAP entry is uniquely identified by a user domain name, which is the position of the entry in the LDAP directory tree.
   Access Password	The password for accessing the LDAP server.
   userSearchFilter	The condition for filtering user search results. For example, users can be filtered by username, email address, or department.
   userSearchBase	The start or base point for user search, namely, the part or organization unit where the user is to be searched.
   groupSearchBase (Optional)	The start or base point for group search.
   groupSearchFilter (Optional)	The filtering condition for group search.
   groupSearchSubtree	Specifies whether to include parameters of sub-trees during group search.
   loginFailedLimit	The maximum number of consecutive logon failures allowed.
   lockTimeSeconds	The interval for resetting the logon count.

3. Click Test Connection.

4. Enter the third-party account and password.

   

5. After the connection test succeeds, the user information API returns structure information. Configure the user field mapping parameters based on the returned information.

   Note

   • The structure returned by a user information API varies based on the third-party application. To map the user information of a third-party application to the user fields in ODC, you must configure the user field mappings. User field mappings identify the ODC account used for LDAP logon.
   • You can configure the Username Field and Nickname Field parameters based on the returned connection information.
   • You can also specify custom fields and custom field mapping rules.
   • The system administrator can configure custom field names through automatic authorization. When you log on to ODC by using custom fields, you are automatically granted the specified roles or permissions.

   

6. Click Save.

7. In the login integration task list, enable the created login integration task.

   

   Note

   You can enable only one login integration task.

8. On the logon page of Web ODC, click LDAP to go to the third-party logon page and use a third-party account to access ODC.

   

Manage login integration tasks

In the login integration task list, you can enable, view, edit, or delete a created login integration task.

References

• Automatic authorization

• Approval integration

• SQL approval integration