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:

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
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.