How to implement role-based SSO from Okta to Alibaba Cloud - Resource Access Management

This topic provides an example of how to configure role-based single sign-on (SSO) between Okta and Alibaba Cloud by using OpenID Connect (OIDC). This configuration enables applications in Okta to securely access Alibaba Cloud resources by exchanging an OIDC token for temporary credentials from the Security Token Service (STS).

Prerequisites

An OIDC application is registered in Okta. The URL of the issuer and the client ID of the application are obtained. The following data is used in this example:

The URL of the issuer is https://dev-xxxxxx.okta.com.
The client ID is 0oa294vi1vJoClev****.

Step 1: Create an OIDC IdP in Alibaba Cloud

In this step, an OIDC identity provider (IdP) named TestOidcProvider is created. The URL of the issuer is https://dev-xxxxxx.okta.com and the client ID is 0oa294vi1vJoClev****.

Log on to the RAM console as a RAM administrator.
In the left-side navigation pane, choose Integrations > SSO.
On the Role-based SSO tab, click the OIDC tab. Then, click Add IdP.

On the Create IdP page, configure the following parameters.

Parameter	Description
IdP Name	The name must be unique within an Alibaba Cloud account.
Issuer URL	The URL of the issuer that is provided by an external IdP. The URL of the issuer must start with `https` and be a valid URL. The URL cannot contain query parameters that follow a question mark (`?`), logon information that is identified by at signs (`@`), or fragment that is identified by number signs (`#`).
Fingerprint	The fingerprint that is generated based on the HTTPS certificate of an external IdP. You can use a fingerprint to prevent the URL of the issuer from being hijacked or tampered with. After you specify a valid value for Issuer URL, you can click Obtain Fingerprint. Alibaba Cloud calculates the fingerprint. We recommend that you calculate the fingerprint on your computer. For example, you can use OpenSSL to obtain the fingerprints of OIDC IdPs. For more information, see Use OpenSSL to obtain the fingerprints of OIDC IdPs. Then, you can compare the calculation result with the calculation result provided by Alibaba Cloud. If the calculation results are different, the URL of the issuer may have been attacked. Make sure that you enter a valid fingerprint. Note If you want to rotate the certificate of your IdP, we recommend that you generate the fingerprint of the new certificate and add the fingerprint to the OIDC IdP that you created in the RAM console before the rotation. After at least one day, rotate the certificate. You can delete the previous fingerprint after you obtain a Security Token Service (STS) token.
Client IDs	The ID that is generated for an application when you register the application in the external IdP. When you apply for an OIDC token from an external IdP, you must use a client ID. The client ID is specified in the `aud` field of the OIDC token that is issued. When you create an OIDC IdP, you must configure the client ID. If you want to use the OIDC token to obtain an STS token, Alibaba Cloud checks whether the client ID that is specified in the `aud` field is the same as the client ID that you configured in the OIDC IdP. You can assume a RAM role only when the client IDs are the same. If multiple clients need to access Alibaba Cloud resources, you can configure multiple client IDs. You can configure a maximum of 50 client IDs.
Earliest Issuance Time Allowed	The time limit on an OIDC token. If an OIDC token is issued earlier than the time limit, the OIDC token cannot be used to obtain an STS token. Default value: 12 hours. Valid values: 1 to 168 hours.
Remarks	The description of the OIDC IdP.

Click OK.

Step 2: Create a RAM role for the OIDC IdP in Alibaba Cloud

In this step, a RAM role named testoidc is created and the TestOidcProvider OIDC IdP that you created in Step 1 is selected.

Log on to the RAM console as a RAM administrator.
In the left-side navigation pane, choose Identities > Roles.
On the Roles page, click Create Role.
In the upper-right corner of the Create Role page, click Switch to Policy Editor.

Specify an OIDC IdP in the editor.

The editor supports the Visual editing and JSON modes.

Visual editor
Specify a specific OIDC IdP for the Principal element.

JSON

Specify an OIDC IdP for the Federated field of the Principal parameter and configure the Condition parameter.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "acs:ram::100*******0719:oidc-provider/xiyun****"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "oidc:iss": [
            "https://dev-xxxxxx.okta.com"
          ],
          "oidc:aud": [
            "0oa294vi1vJoClev****"
          ]
        }
      }
    }
  ]
}

Specify conditions in the editor.

The following table lists the supported service-level condition keys.

Condition key	Description	Required	Example
`oidc:iss`	The issuer. You can assume the RAM role only if the iss field of the OIDC token that you want to use to assume the RAM role meets this condition. The conditional operator must be StringEquals. The value must be the URL of the issuer that you specify for the selected OIDC IdP. You can specify this condition to ensure that you can use the OIDC token to assume the RAM role only if the OIDC token is issued by a trusted IdP.	Yes	https://dev-xxxxxx.okta.com
`oidc:aud`	The audience. You can assume the RAM role only if the aud field of the OIDC token that you want to use to assume the RAM role meets this condition. The conditional operator must be StringEquals. The value can be one or more client IDs that you specify for the selected OIDC IdP. You can specify this condition to ensure that you can use the OIDC token to assume the RAM role only if the OIDC token is generated by using the client ID that you specify.	Yes	0oa294vi1vJoClev****
`oidc:sub`	The subject. You can assume the RAM role only if the sub field of the OIDC token that you want to use to assume the RAM role meets this condition. The conditional operator can be a string of all types. The value can be up to 10 subjects. You can specify this condition to further limit the identity that you can use to assume the RAM role. You can also leave this condition unspecified.	No	00u294e3mzNXt4Hi****

In the Create Role dialog box, configure the Role Name parameter and click OK.

Step 3: Grant permissions to the RAM role

You can grant permissions to the RAM role named testoidc that you created in Step 2 to access Alibaba Cloud resources based on your business requirements.

Log on to the RAM console as a RAM administrator.
In the left-side navigation pane, choose Identities > Roles.
On the Roles page, find the RAM role that you want to manage and click Grant Permission in the Actions column.
You can also select multiple RAM roles and click Grant Permission in the lower part of the RAM role list to grant permissions to multiple RAM roles at a time.
In the Grant Permission panel, grant permissions to the RAM role.
1. Configure the Resource Scope parameter.
  - Account: The authorization takes effect on the current Alibaba Cloud account.
  - Resource Group: The authorization takes effect on a specific resource group.
    Note
    If you select Resource Group for the Resource Scope parameter, make sure that the required cloud service supports resource groups. For more information, see Services that work with Resource Group.
2. Configure the Principal parameter.
  The principal is the RAM role to which you want to grant permissions. The current RAM role is automatically selected.
3. Configure the Policy parameter.
  A policy is a set of access permissions. You can select multiple policies at a time.
  - System policies: policies that are created by Alibaba Cloud. You can use but cannot modify these policies. Version updates of the policies are maintained by Alibaba Cloud. For more information, see Services that work with RAM.
    Note
    The system automatically identifies high-risk system policies, such as AdministratorAccess and AliyunRAMFullAccess. We recommend that you do not grant unnecessary permissions by attaching high-risk policies.
  - Custom policies: You can manage and update custom policies based on your business requirements. You can create, update, and delete custom policies. For more information, see Create a custom policy.
4. Click Grant permissions.
Click Close.

Step 4: Obtain an OIDC token from Okta

Alibaba Cloud uses OIDC for programmatic access only, not for console logon. To get an OIDC token from an IdP like Okta, you must use a standard OAuth 2.0 flow, such as the Authorization Code Flow.

The following example is based on the official Okta tutorial Sign users in to your SPA using redirect and Auth JS and demonstrates how to obtain an OIDC token from Okta.

Follow the Okta tutorial to create an application and configure the project.

Test the project in a browser. The application automatically redirects to the Okta logon page. After you log on and complete multi-factor authentication (MFA), the page redirects to index.html. The page displays the ID Token for the current user and its parsed claims, as shown below:

{
  "idToken": "eyJraWQiOiItbUF****",
  "claims": {
    "sub": "00uxbq0z40UYy9bm****",
    "name": "ssotest01",
    "email": "ssotest01@exampledomain.com",
    "ver": 1,
    "iss": "https://dev-xxxxxx.okta.com",
    "aud": "0oaxbqhfrfBl5lk2****",
    "iat": 1762841679,
    "exp": 1762845279,
    "jti": "ID.WYtCLmLKOlMcEh0uIe1jWH9T6M1JmotCvX3hIgLK6mA",
    "amr": [
      "mfa",
      "otp",
      "pwd",
      "okta_verify"
    ],
    "idp": "00oxbpgns1TnfLFg****",
    "nonce": "Xp0PTyQzw9ltYBY7SfhxG2ijt1wgi2jK6XLZOGbeQJQ79d0ScWYoHE5twl0QAklA",
    "preferred_username": "ssotest01@exampledomain.com",
    "auth_time": 1762841677,
    "at_hash": "wztv8ALAo2Au56Om3dya7w"
  },
  "expiresAt": 1762845279,
  "scopes": [
    "openid",
    "profile",
    "email"
  ],
  "authorizeUrl": "https://dev-xxxxxx.okta.com/oauth2/v1/authorize",
  "issuer": "https://dev-xxxxxx.okta.com",
  "clientId": "0oaxbqhfrfBl5lk2****"
}

Note

From the claims displayed on the page, locate the following properties. Ensure that they match the OIDC IdP information that you configured in Step 1: Create an OIDC IdP in Alibaba Cloud. If they do not match, the call to the AssumeRoleWithOIDC operation fails.

iss: Must exactly match the Issuer URL.
aud: Must exactly match the Client ID.

Copy the idToken value from the page and save it.

Step 5: Exchange the OIDC token for an STS token

Call the AssumeRoleWithOIDC operation to obtain an STS token. In the request, specify the OIDC token (ID token) that you obtained in Step 4.

Sample request:

package demo;
import com.aliyun.auth.credentials.provider.AnonymousCredentialProvider;
import com.aliyun.sdk.service.sts20150401.models.*;
import com.aliyun.sdk.service.sts20150401.*;
import com.google.gson.Gson;
import darabonba.core.client.ClientOverrideConfiguration;
import java.util.concurrent.CompletableFuture;


public class AssumeRoleWithOIDC {
  public static void main(String[] args) throws Exception {

    // Anonymous access method (requires API support)
    AnonymousCredentialProvider provider = AnonymousCredentialProvider.create();

    // Configure the Client
    AsyncClient client = AsyncClient.builder()
      .region("cn-hangzhou") // Region ID
      .credentialsProvider(provider)
      // Client-level configuration rewrite, can set Endpoint, Http request parameters, etc.
      .overrideConfiguration(
        ClientOverrideConfiguration.create()
        // Specify the endpoint of the region in which the bucket is located. For more information, visit https://api.alibabacloud.com/product/Sts.
        .setEndpointOverride("sts.cn-hangzhou.aliyuncs.com")
      )
      .build();

    String idToken = "eyJraWQiOiItbUF****"; // OIDC id token
    // Parameter settings for API request
    AssumeRoleWithOIDCRequest assumeRoleWithOIDCRequest = AssumeRoleWithOIDCRequest.builder()
      .OIDCToken(idToken)
      .roleArn("acs:ram::173305794806****:role/testoidc")
      .OIDCProviderArn("acs:ram::173305794806****:oidc-provider/Okta")
      .roleSessionName("test-oidc-session")
      .build();
    // Asynchronously get the return value of the API request
    CompletableFuture<AssumeRoleWithOIDCResponse> response = client.assumeRoleWithOIDC(assumeRoleWithOIDCRequest);
    // Synchronously get the return value of the API request
    AssumeRoleWithOIDCResponse resp = response.get();
    System.out.println("RequestId: " + resp.getBody().getRequestId());
    System.out.println("Assume role ARN: " + resp.getBody().getAssumedRoleUser().getArn());
    System.out.println("Credentials AccessKeyId: " + resp.getBody().getCredentials().getAccessKeyId());
    System.out.println("Credentials AccessKeySecret: " + resp.getBody().getCredentials().getAccessKeySecret());
    System.out.println("Success response: " + new Gson().toJson(resp.getBody()));

    // Finally, close the client
    client.close();
  }

}

Sample response:

RequestId: 5EB6E605-15EA-5D96-941D-2C62DC99****
Assume role ARN: acs:ram::173305794806****:role/testoidc/test-oidc-session
Credentials AccessKeyId: STS.NZXMTBGTTHLW74AMVYKou****
Credentials AccessKeySecret: FdrYjJwTCfFfMdY4APdHsjGL9fH5RSZCtRyYMJED****
Success response:
{
    "assumedRoleUser": {
        "arn": "acs:ram::173305794806****:role/testoidc/test-oidc-session",
        "assumedRoleId": "30048007026011****:test-oidc-session"
    },
    "credentials": {
        "accessKeyId": "STS.NZXMTBGTTHLW74AMVYKou****",
        "accessKeySecret": "FdrYjJwTCfFfMdY4APdHsjGL9fH5RSZCtRyYMJED****",
        "expiration": "2025-11-11T08:01:03Z",
        "securityToken": "CAISwwJ1q6Ft5B2yfSjI****"
    },
    "OIDCTokenInfo": {
        "clientIds": "0oaxbqhfrfBl5lk2****",
        "expirationTime": "2025-11-11T07:14:39Z",
        "issuanceTime": "2025-11-11T06:14:39Z",
        "issuer": "https://dev-xxxxxx.okta.com",
        "subject": "00uxbq0z40UYy9bm****",
        "verificationInfo": "Success"
    },
    "requestId": "5EB6E605-15EA-5D96-941D-2C62DC99****"
}

The information in Credentials is the information about the STS token.

Step 6: Use the STS token to access Alibaba Cloud resources

Use the STS token that you obtained from Step 5 to access the Alibaba Cloud resources on which you have permissions.