Updated on 2024-07-30 GMT+08:00

Obtaining an Unscoped Token (IdP Initiated)

Function

This API is used to obtain an unscoped token through IdP-initiated federated identity authentication.

Unscoped tokens cannot be used for authentication. A federated user can be authenticated only using a scoped token. For details, see Obtaining a Scoped Token.

The API can be called using both the global endpoint and region-specific endpoints. For IAM endpoints, see Regions and Endpoints.

  • This API can be called using the CLI. The client can call this API to obtain a SAML response in IdP-initiated authentication mode and obtain an unscoped token through a browser.

Debugging

You can debug this API in API Explorer.

URI

POST /v3.0/OS-FEDERATION/tokens

Request Parameters

Table 1 Parameters in the request header

Parameter

Mandatory

Type

Description

Content-Type

Yes

String

The client must use a browser to transfer SAML response parameters to the server. Set this parameter to application/x-www-form-urlencoded.

X-Idp-Id

Yes

String

Identity provider ID.

Table 2 Parameters in the request formData

Parameter

Mandatory

Type

Description

SAMLResponse

Yes

String

Response body to be returned if IdP authentication is successful.

Perform the following procedure to obtain a SAML response:

  1. Visit https://idp.example.org/idp/profile/SAML2/Unsolicited/SSO?providerId=iam.example.com using a browser.

    idp.example.org: Entity ID in the IdP metadata

    iam.example.com: Entity ID in the SP metadata

  2. On the displayed identity provider login page, enter a username and then click Login (password-free login is supported). On the new page that is displayed, press F12 and click Accept. Obtain the SAML response from POST as shown in the following figure.
    Figure 1 Obtaining a SAML response

Response Parameters

Table 3 Parameters in the response header

Parameter

Type

Description

X-Subject-Token

String

Signed unscoped token.

Table 4 Parameters in the response body

Parameter

Type

Description

token

Object

Details of the unscoped token.

Table 5 token

Parameter

Type

Description

issued_at

String

Time when the token was issued.

NOTE:

The value is a UTC time in the YYYY-MM-DDTHH:mm:ss.ssssssZ format, for example, 2023-06-28T08:56:33.710000Z. For details about the date and timestamp formats, see ISO-8601.

expires_at

String

Time when the token will expire.

NOTE:

The value is a UTC time in the YYYY-MM-DDTHH:mm:ss.ssssssZ format, for example, 2023-06-28T08:56:33.710000Z. For details about the date and timestamp formats, see ISO-8601.

methods

Array of strings

Method for obtaining the token.

user

Object

Information about the IAM user who requests for the token.

Table 6 token.user

Parameter

Type

Description

domain

Object

Information about the account used to create the IAM user.

id

String

User ID.

name

String

Username.

OS-FEDERATION

Object

Federated identity authentication information.

Table 7 token.user.domain

Parameter

Type

Description

name

String

Account name.

id

String

Account ID.

Table 8 token.user.OS-FEDERATION

Parameter

Type

Description

groups

Array of objects

User group information.

identity_provider

Object

Identity provider information.

protocol

Object

Protocol information.

Table 9 token.user.OS-FEDERATION.groups

Parameter

Type

Description

id

String

User group ID.

name

String

User group name.

Table 10 token.user.OS-FEDERATION.identity_provider

Parameter

Type

Description

id

String

Identity provider ID.

Table 11 token.user.OS-FEDERATION.protocol

Parameter

Type

Description

id

String

Protocol ID.

Example Request

Request for obtaining an unscoped token (IdP initiated)

POST https://iam.myhuaweicloud.com/v3.0/OS-FEDERATION/tokens
SAMLResponse=PD94b...

Example Response

Status code: 201

The request is successful.

Parameters in the response header
X-Subject-Token:MIIatAYJKoZIhvcNAQcCoIIapTCCGqECAQExDTALB...
Parameters in the response body
{
    "token": {
        "expires_at": "2020-02-13T14:21:34.042000Z",
        "methods": [
            "mapped"
        ],
        "issued_at": "2020-02-12T14:21:34.042000Z",
        "user": {
            "OS-FEDERATION": {
                "identity_provider": {
                    "id": "ACME"
                },
                "protocol": {
                    "id": "saml"
                },
                "groups": [
                    {
                        "id": "06aa22601502cec4a23ac0084a74038f",
                        "name": "admin"
                    }
                ]
            },
            "domain": {
                "name": "IAMDomain",
                "id": "06ba0970a097acc0f36c0086bb6cfe0"
            },
            "name": "FederationUser",
            "id": "LdUTYSC7zmJVIic3yaCbLBXDxPAdDxLg"
        }
    }
}

Status Codes

Status Code

Description

201

The request is successful.

400

Invalid parameters.

401

Authentication failed.

403

Access denied.

405

The method specified in the request is not allowed for the requested resource.

413

The request entity is too large.

500

Internal server error.

503

Service unavailable.

Error Codes

None