Alibaba Cloud

Prerequisites

We recommend granting the AliyunAgentIdentityFullAccess permission to the operator.

Step 1: Create an OAuth application in RAM

To perform this step and Step 2, the operator requires the following RAM permissions:

• ram:ListApplications

• ram:CreateApplication

• ram:GetApplication

• ram:UpdateApplication

Sample policy:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ram:ListApplications",
        "ram:GetApplication",
        "ram:CreateApplication",
        "ram:UpdateApplication"
      ],
      "Resource": "*"
    }
  ]
}

1. Sign in to the RAM console. In the left-side navigation pane, choose Integrations > OAuth Applications (Public Preview).

2. On the OAuth Applications page, on the default Enterprise Applications tab, click Create Application.

3. On the Create Application page, set the application parameters.

   1. Enter an Application Name and a Display Name.

   2. Set OAuth Protocol Version to 2.1.

   3. Set Application Type to Web App.

   4. Set the Access Token Validity Period (Optional). This affects the validity period of the id_token and access_token issued by Alibaba Cloud.

   5. Redirect URI: The URI to which the authorization server redirects the user after successful authorization. It receives the authorization code and exchanges it for an id_token and an access_token at the Alibaba Cloud OAuth token endpoint. For example: https://your-app-fqdn/authcallback.

   6. OAuth Scopes: Keep the default openid scope selected. To retrieve RAM user information such as the logon name (UPN) and display name, also select the profile scope.

4. Click Create Application.

5. Click the application that you created. On the application details page, in the Basic Information section, copy and save the Application ID.

Step 2: Test obtaining an ID Token (Optional)

Manually construct an OAuth request to obtain an ID Token for testing the authentication flow or debugging your application.

1. On the RAM console, open the OAuth application that you created in Step 1. In the Basic Information section, click Edit next to Redirect URIs.

2. Click Add, enter http://localhost:8080, and then click OK.

3. Copy the following HTTP request and replace <YOUR-OAUTH-APPLICATION-ID> with the application ID that you saved in Step 1.

   https://signin.aliyun.com/oauth2/v1/auth?
   client_id=<your-oauth-application-id>
   &redirect_uri=http://localhost:8080
   &response_type=code
   &scope=openid
   &state=12345
   &code_challenge=XLtBsMIdIa2SGFvlnDsWLBrtPxVtSekmqUbVDB8a1Pc
   &code_challenge_method=S256

4. Access the request URL in a browser. Follow the on-screen instructions to complete RAM user logon and authorization. After the process completes, the browser redirects to http://localhost:8080 and returns the authorization code code in the URL. Copy the value of code from the URL and save it.

   http://localhost:8080/?state=12345&code=eZ6Xq***

5. Copy and run the following command. Replace <your-authorization-code> and <your-oauth-application-id> with the authorization code from the previous step and the OAuth application ID from Step 1, respectively.

   curl -X POST "https://oauth.aliyun.com/v1/token" \
        -H "Content-Type: application/x-www-form-urlencoded" \
        -d "code=<your-authorization-code>" \
        -d "client_id=<your-oauth-application-id>" \
        -d "redirect_uri=http://localhost:8080" \
        -d "grant_type=authorization_code" \
        -d "code_verifier=ZURxphBVsaMxQXMbRGA4lkUr9myW5jvwLKR5l1dYnsc"

   Note

   An Alibaba Cloud OAuth authorization code is valid for 10 minutes. You must exchange the code for an ID Token within this 10-minute window. If the authorization code expires, you must restart the authorization process to get a new one.

6. A successful response contains id_token and access_token.

   {
     "scope": "openid",
     "request_id": "0cb612ae-4210-4a57-bec1-86f57f5d****",
     "access_token": "eyJhbGciOiJSUzI1NiIsImsyaWQ...bGwBLQ",
     "token_type": "Bearer",
     "id_token": "eyJraWQiOiJQY1BjK29hamVsRnRnUW5...5w9GTw",
     "expires_in": 3599
   }

7. Copy the value of id_token to a JWT parsing website, such as https://www.jwt.io/, to view the decoded ID Token. The value of the aud field should exactly match the OAuth application ID.

   {
     "aud": "401050526640555****",
     "sub": "iiCsOvhjNZX/hK0x1jl9****",
     "iss": "https://oauth.aliyun.com",
     "exp": 1766463919,
     "iat": 1766460319
   }

Step 3: Create an identity provider in Agent Identity

1. Sign in to the Agent Identity console. In the left-side navigation pane, choose Inbound > Identity Providers.

2. On the Identity Providers page, click Create Identity Provider.

3. On the Create Identity Provider page, enter the following information:

   • Identity Provider Name. Enter a custom name for the identity provider.

   • Description (Optional).

   • OIDC Discovery URL. Enter the Alibaba Cloud OIDC discovery URL https://oauth.aliyun.com/.well-known/openid-configuration.

   • Allowed Audiences. Keep the default Specify audience allowlist option selected, and enter the Alibaba Cloud OAuth Application ID that you created in Step 1. To support multiple audiences, you can enter multiple OAuth Application IDs, separated by newlines.

4. Click Create Identity Provider.

Step 4: Associate the identity provider with a workload identity in Agent Identity

An identity provider must be associated with a workload identity to enable inbound authorization. If you have not created a workload identity, see Create a workload identity.

1. Sign in to the Agent Identity console. In the left-side navigation pane, choose Workload Identities.

2. On the Workload Identities page, click the target workload identity.

3. On the workload identity details page, in the Authentication Flow section, click Associate Identity Provider under Identity Providers.

4. In the Associate Identity Provider dialog box, select the identity provider that you created in Step 3 from the drop-down menu.

5. Click OK.