Configure SSO integration

OCP has its own built-in account system. You can refer to this topic to configure external integration services in OCP and log in to the OCP homepage through SSO.

Prerequisites

• You have understood the concept and authorization process of SSO by referring to Overview.
• Ensure the current user logged in to OCP is in the ADMIN role.
• The authorization service has been deployed.

Considerations

• OAUTH/OIDC integration only supports the authorization code mode.
• When logging out of OAUTH/OIDC, only the login state in the OCP application is cleared; the login state in the SSO system is not cleared.

Procedure

1. Log in to OCP.

2. Click Administration > Integrations in the left navigation bar to go to the SSO Integrations page.

3. Click Create SSO Integration in the upper-right corner, and configure the gateway authentication parameters in the pop-up window.

   Parameter	Description
   Configuration Name	The configuration name will be applied to the custom login name. It must start with a letter, end with a letter or number, can contain letters, numbers, and underscores, and be 2 to 32 characters long.
   Type	Select the service type for the external account, including OAuth2 and OIDC.
   Enable Local Login Mode	Specifies whether to support local username/password login mode.
   Client ID	The unique identifier for the OAuth2/OIDC authorization server application.
   Client Secret	The authentication key for the OAuth2/OIDC authorization server application.
   Auth URL	The authorization endpoint URL of the OAuth2/OIDC authorization server, used to initiate an authorization request.
   User Info URL	The user information endpoint URL of the OAuth2/OIDC authorization server, used to obtain user information.
   Token URL	The token endpoint URL of the OAuth2/OIDC authorization server, used to exchange the authorization code for an access token.
   Redirect URL	By default, the domain name of the Redirect URL must match the domain name specified by the ocp.site.url system parameter in OCP. If they do not match, you need to modify the domain name configuration of ocp.site.url.
   Scope	The requested OAuth2 authorization scope, which defines the user information permissions the application needs to access. Common Scopes include openid, profile, email, etc. Notice The OIDC protocol defines the openid Scope by default. This Scope cannot be used under the OAuth2 protocol, otherwise unknown issues may occur.
   jwkSet URL	An advanced option, optional. The JSON Web Key Set (JWKS) endpoint URL for verifying JWT tokens. Required when using JWT token verification, typically used with the OIDC protocol.
   Issue URL	An advanced option, optional. The endpoint URL for obtaining an ID Token. Required when using the OIDC protocol.
   Client Authentication Method	An advanced option, optional. The method by which the client authenticates with the authorization server, including basic, client_secret_basic, post, client_secret_post, client_secret_jwt, private_key_jwt, and none. Default is client_secret_basic. For details, see the configuration instructions at the end of this topic.
   Authorization Grant Type	An advanced option, optional. Currently only supports the authorization code mode; other modes are not supported. For details, refer to the OAuth2 authorization modes described in Overview.
   User Info Authentication Method	An advanced option, optional. The authentication method used when obtaining user information. Default is Header. For details, see the configuration instructions at the end of this topic.

4. Click Test Connection.

   • If the connection succeeds, the page will redirect to the third-party authorization login page. Enter your third-party login credentials and click Third-Party Login to authorize access to OCP. The OCP page will then display The connection test is successful..

   • If the connection fails, the page will display Connection test failed. You can troubleshoot and modify based on the error message from the test result.

5. After the test connection succeeds, return the structure of the user information API. You can fill in the user field mapping parameters based on the returned information.

   Parameter	Description
   User Information Data Structure Type	Supports two types: FALT and NESTED. The default is FALT, which means flat; NESTED means embedded. For details, see the Configuration section at the end of this topic.
   Get Nested User Data	When the user information data structure type is set to NESTED, you must first fill in the nested user data, and then set the username field.
   Username Field	The name of the username field in the User Info URL interface.
   Email Field	Optional. The name of the email field in the User Info URL interface.

   Note

   The structure returned by the user information API varies by third-party application. To map the user information from a third-party application to OCP user fields, you need to fill out the user information mapping form. User field mapping identifies the identifier for the OCP account associated with the OAuth2 login.

6. Click Save to complete the creation of the SSO integration.

7. Refer to Enable/Disable SSO Integration Configuration to enable the created SSO integration in the SSO Integrations.

Configuration instructions

Client Authentication Method

The Client Authentication Method is the way a client application proves its identity to an authorization server in OAuth2, OIDC, or other API security protocols. You can choose an appropriate authentication method based on the client type and security requirements.

client_secret_basic

• Method: Uses HTTP Basic authentication.
• Implementation: Base64-encode the client-id and client-secret, and include them in the HTTP request header as Authorization: Basic ....

client_secret_post

• Method: Includes the credentials as parameters in the POST request body.
• Implementation: Include the client_id and client_secret parameters in the request body.

client_secret_jwt

• Method: Uses a JWT signed with a symmetric key (Client Secret).
• Implementation: The client generates a JWT containing claims and signs it with the client_secret as the authentication credential.

private_key_jwt

• Method: Uses a JWT signed with an asymmetric key (private key).
• Implementation: The client signs the JWT with its own private key, and the authorization server verifies the signature using a pre-configured public key.

none

• Method: No client authentication is performed.
• Application scenario: Typically used for Public Clients (such as mobile apps or SPA applications), which cannot securely store secrets. Often used in conjunction with the PKCE process.

User Info Authentication Method

In OAuth2, the User Info Authentication Method refers to the way the client verifies its identity to the server when requesting the User Info endpoint. The three common methods are as follows:

Query

Append the client credentials (such as client_id and client_secret) as query parameters in the URL.

For example:

GET /user_info?access_token=xxx&client_id=abc&client_secret=def

This method is not recommended because the URL may be logged or cached, posing a risk of leakage.

Header

Use the HTTP Authorization header for authentication, typically including base64-encoded client_id:client_secret as Basic Auth information.

For example:

Authorization: Basic base64encode(client_id:client_secret)

This method is more secure, but you must ensure encryption during the communication process (such as using HTTPS).

Form

Submit the client credentials in the request body in a form format.

For example:

POST /user_info
Content-Type: application/x-www-form-urlencoded
client_id=abc&client_secret=def

This method is commonly used with the client_credentials authorization type and must be used together with the Content-Type header.

User information data structure types

FALT

The FALT method indicates flattened. Assuming the user field is username, the following return format is flattened:

{
"username":"xxx"
}

NESTED

The NESTED method indicates nested, meaning username is embedded within the userInfo structure. When the user information data structure type is set to NESTED, you need to fill in userInfo when retrieving nested user data, and then set the username field:

{
    "userInfo":{
        "username":"xxx"
    }
}