In the previous two articles, we introduced the OIDC authorization code and the PKCE mode enhanced by the authorization code. This time we will focus on the (Client Credentials) mode. The Client Credentials mode is one of the OIDC authorization modes. An authentication and authorization mode in which the client (application) obtains an access token (access token) from the OIDC server in its own name, and is often used to protect APIs or IoT scenarios.
[ Authing is the only developer-centric full-scenario identity cloud product in China, providing 1000+ APIs and all mainstream language SDKs, and has a community ecology of hundreds of thousands of developers. 】
01. Client Credentials
The Client Credentials mode is used for server-to-server authorization (M2M authorization) without user participation. You need to create a programming access account in advance, and hand over the AK and SK key pair to your resource caller. It should be noted that each vendor implements this differently. For example, the implementation of Client Credentials by Okta and Auth0 is to use Client The ID and Client Secret are handed over to the caller, and Authing is to create a programmatic access account under the application and hand over the AK/SK to the caller. There is no difference in the use of the caller. The Authing method is more suitable for multiple The caller manages.
⚠️ Client Credentials mode does not support Refresh Token.
Overall, there are the following processes:
1. The resource caller sends his credentials AK, SK and the scope of the permission to be requested to the Authing authorization endpoint.
2. If the credentials are correct and the caller has resource permissions, Authing issues an AccessToken for it.
3. The caller carries the access_token to request the resource server.
4. After the resource server verifies that the token passes, it returns the relevant resources.
The flow chart is as follows:
1.1 Prepare to connect
1.1.1 Create an application and configure it in Authing
As usual, you need to create an application in Authing first.
Configure authorization mode
Create a programmatic access account and give it to your API caller
1.1.2 Define authority in Auhing and authorize AK SK account
Note: During user authentication, scope corresponds to user information, and when AK/SK obtains Token, scope should correspond to authorized API authority.
1.1.2.1 Scope permission specification
The scope permission items of Authing are separated by spaces, and the format of each item is
resource:resource-identifier:resource-operation
resource: resource identifier: resource operation.
The following are all scope formats supported by Authing:
1. The meaning is the read permission of the book resource numbered 1
book:1:read
2. The meaning is the read permission of all book resources
book:*:read
3. The meaning is the read permission of all book resources
book:read
4. The meaning is all operation permissions of all book resources
book:*:*
5. The meaning is all operation permissions of all book resources
book:*
6. The meaning is all operation permissions of all book resources
book:
7. It means all operation permissions of all resources
*:*:*
8. It means all operation permissions of all resources
*:*
9. It means all operation permissions of all resources
*
1.1.2.2 Define related resources in Authing authority management
We define the book resource:
1.1.2.3 Authorize Programmatic Access Accounts
Here we authorize caller A of the programming access account just created, allowing caller A to access the /book API with a GET request, and can only obtain the order with ID 20150
1.2 Access test
1.2.1 List of required calling interfaces
POST${host}/oidc/token 获取 Token
POST${host}/oidc/token/introspection 校验 Token
POST${host}/oidc/revocation 吊销 Token
1.2.2 Run in Postman
The interface to be introduced below can be experienced by fork through our online postman collection
1.2.3 Get Token
POST${host}/oidc/token
After the user completes the login operation on the Authing side, Authing will call back the generated code as a parameter to the redirect_uri address. At this time, the corresponding access token access_token can be obtained through the code-for-token interface
Example request :
curl --location 'https://{host}/oidc/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={AccessKey}' \
--data-urlencode 'client_secret={SecretKey}' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=book:20150:GET book:20150:POST'
Example response (success) :
{
"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Il9xcEhRQXFvbXd0Z3BKX2xZVHNtN2FMVEU3YUtJb0tQeFN5by1faDdGUVkifQ.eyJhenAiOiI2M2Y0ODA5OTlkNGY0MDRiZTViNDQ0NGEiLCJhdWQiOiI2M2Y0ODI1ZDhhNWRmNjYyNTU4YjI4MTQiLCJzY29wZSI6ImJvb2s6MjAxNTA6R0VUIiwiaWF0IjoxNjgxNzExNDU2LCJleHAiOjE2ODE3MTIwNTYsImp0aSI6IlBiSks5djNFTS1rS1o3bms4VmdBRms3eVVPRzJES2NwYUQ2M2gxaThmVlkiLCJpc3MiOiJodHRwczovL29pZGMtY2xpZW50LWNyZWRlbnRpYWxzLmF1dGhpbmcuY24vb2lkYyJ9.qPcJU84C9Ztjm5dk-im8ntatPaB5P8j3ZPdW1eoi-V5po8k32jexUemSEHInEfqdxcnY7OyR1pph6JVjehmoCAX6gqA_3fv20hUjnWQNqcZegAiNea4jQbLKlMsYnTQhhJWmzhs64LwCJD1RqQy0VtoL2ZVVfAEpySHWL6TwWVz0AkvQpZbzkF6FRCa03rli_jc1BNtpGUhvNdtGs6xJMMLJZ31dptrLlSSWSQ71t05fqBfEiToN6-JkwKXJedpHBvFWt_-XncQbksdQQc6krTcgaWkrIbv6LblTrtAifXLfOsANweOAG8QoKLh55vSMMBXdzdw-IzXeCDuwQT5P2w",
"token_type":"Bearer",
"expires_in":600,
"scope":"book:20150:GET",
"rejected_scope":"book:20150:POST"
}
Here scope is the resource that should be allowed to be accessed by the access account, and rejected_scope is the permission that we applied for but was rejected. We just assigned the permission of book:20150:GET to caller A, so we request book:20150: at the same time. GET and book:20150:POST permissions, the book:20150:POST permission will be rejected, and the caller can use the token to call the protected API after obtaining the access_token.
Example response (failed) :
{
"error": "server_error",
"error_description": "编程访问账号不存在！"
}
1.2.4 Verify Token
POST${host}/oidc/token/introspection
After the API server receives the interface call request, it can call this interface to verify the validity of the access_token and whether it has permission to call the corresponding API.
This endpoint accepts access_token, id_token, refresh_token and returns a boolean indicating if it is active or not. If the token is active, additional data about the token will also be returned. A token is considered inactive if it is invalid, expired, or revoked.
access_token can be signed with RS256 signature algorithm or HS256 signature algorithm. Here is the difference between the two signature algorithms:
RS256 is a digital signature algorithm using the RSA algorithm, which uses a public/private key pair to encrypt and verify information. Tokens generated with RS256 signatures are more secure than tokens generated with HS256 signatures because signing with an RSA key pair provides a higher level of protection. Tokens using the RS256 signature algorithm can be verified using the public key, which can be obtained through the JWK endpoint.
HS256 is a digital signature algorithm using a symmetric key. It uses the same key for signing and verification. The HS256 signature algorithm is faster in performance than the RS256 signature algorithm because it uses a symmetric key instead of an RSA public/private key pair for signing and verification. Tokens using the HS256 signature algorithm can be verified by a shared secret (application key).
In practical applications, the RS256 algorithm is more secure, but it also consumes more resources. If the system requires high performance, you can choose the HS256 signature algorithm. Online verification :
Request parameters :
Example request :
curl --location --request POST 'https://{host}/oidc/token/introspection' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={应用ID}' \
--data-urlencode 'client_secret={应用密钥}' \
--data-urlencode 'token={ token }' \
--data-urlencode 'token_type_hint=access_token'
Verification access_token response example (verification passed)
{
"active": true,
"aud": "63f4825d8a5df662558b2814",
"client_id": "63f480999d4f404be5b4444a",
"exp": 1681713127,
"iat": 1681712527,
"iss": "https://oidc-client-credentials.authing.cn/oidc",
"jti": "EpveFqLsgskNIre8fK-h0AOK6oBIfZH6erT5iSrRKmd",
"scope": "book:20150:GET",
"token_type": "Bearer"
}
Verification access_token response example (verification failed):
{
"active": false
}
1.2.5 Withdraw Token
POST${host}/oidc/token/revocation
The API service can revoke the caller's access_token through this interface.
Request parameters :
Example request :
curl --location --request POST 'https://{host}/oidc/token/revocation' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={应用ID}' \
--data-urlencode 'client_secret={应用密钥}' \
--data-urlencode 'token= {token}' \
--data-urlencode 'token_type_hint=access_token'
Example response (success) :
HTTP 200 OK
Example response (failed) :
{
"error": "xxxx","error_description": "xxxx"
}
02. Summary of this chapter
In this chapter, we introduced the use of the Client Credentials mode to protect APIs. So far, we have introduced the commonly used authorization modes of OIDC.
[Authing is the only developer-centric full-scenario identity cloud product in China, providing 1000+ APIs and all mainstream language SDKs, with a community ecology of hundreds of thousands of developers. 】
The following is the catalog of articles in the OIDC & OAuth2.0 authentication protocol best practice series, click the link to view the original text:
Edited at 2023-04-27 11:45