All pages
Powered by GitBook
1 of 4

Token Lifecycle Management Mechanism

Applying Refresh Token

After user authentication is completed, both the access token and refresh token will be returned. When the access token expires, you can use the refresh token to obtain a new access token.

Example request:

curl -v -X POST https://{digiRunner_DOMAIN}/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic {client_secret}' \
-d 'grant_type=refresh_token' \
-d 'refresh_token={refresh_token}'

Parameters with details:

Parameter
Type
Requirement
Description

client_secret

String

Required

Scenario I. Higher-Security (Client Password Required)

1. Client Password registered with digiRunner; needs to be encoded with Base64

2. Concatenate the client ID with ":" and the encoded client password, then encode the result with Base64 again to generate the value to be used

3. Example:

Client ID: tspclient

Client Password: tsp123abcd

Formula for generating the value:

Base64 Encode(ClientID+":"+Base64 Encode(Client Password))

Base64 Encode(tspclient+":"+Base64 Encode(tsp123abcd))

Base64 Encode(tspclient:dHNwMTIzYWJjZA==)

Output for client_secret:

dHNwY2xpZW50OmRITndNVEl6WVdKalpBPT0=

Scenario II. PKCE + Public Client (Client Password Not Required)

When the Public Client (With PKCE) option is selected in digiRunner's OAuth grant type, the client password is not required.

1. Concatenate the client ID with ":" (no client password is required)

2. Example:

Client ID: tspclient

Client Password: ""

Formula for generating the value:

Base64 Encode(ClientID+":")

Base64 Encode(tspclient+":")

Base64 Encode(tspclient:)

Output for client_secret:

dHNwY2xpZW50Og==

grant_type

String

Required

refresh_token, a fixed value

refresh_token

String

Required

Refresh Token, associated with the access token that requires refreshing

If the refresh token has expired, you must prompt the user to log in again to generate a new access token.

Example of Successful Response

If the refresh is successful, a new access token will be returned.

Example:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJub2RlIjoiZXhlY3V0b3IxIiwiYXVkIjpbIllXUnRhVzVCVUVrIl0sInVzZXJfbmFtZSI6InRzcHVzZXIiLCJvcmdfaWQiOiIxMDAwMDAiLCJzY29wZSI6WyIyMDAwMDAwMDA2Il0sInN0aW1lIjoxNjg0ODA5NzE3NjY4LCJleHAi...",
    "expires_in": 86399,
    "jti": "41fa8a7b-b21d-4598-b254-5ffbed8b619f",
    "node": "executor1",
    "org_id": "100000",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJub2RlIjoiZXhlY3V0b3IxIiwiYXVkIjpbIllXUnRhVzVCVUVrIl0sInVzZXJfbmFtZSI6InRzcHVzZXIiLCJvcmdfaWQiOiIxMDAwMDAiLCJzY29wZSI6WyIyMDAwMDAwMDA2Il0sImF0aSI6ImMyYzAzNTc0LTI2ODItNGYwMi...",
    "scope": "2000000006",
    "stime": 1684742522981,
    "token_type": "bearer"
}

Example of Error Response

If the refresh token has expired, a 401 Unauthorized HTTP status code and JSON response will be returned.

Example:

{
    "error": "invalid_token",
    "error_description": "Invalid refresh token (expired): eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJub2RlIjoiZXhlY3V0b3IxIiwiYXVkIjpbIllXUnRhVzVCVUVrIl0sInVzZXJfbmFtZSI6InRzcHVzZXIiLCJvcmdfaWQiOiIxMDAwMDAiLCJzY29wZSI6WyIyMDAwMDAwMDA2Il0sImF0aSI6ImMyYzAzNTc0LTI2ODItNGYwMi..."
}

Token Revocation

The section illustrated how to invalidate the access token and refresh token. When users log out of your application, revoke their access token.

Example request:

curl -v -X POST https://{digiRunner_DOMAIN}/oauth/revocation \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'token={access_token} \
-d 'token_type_hint=access_token' \
-d 'client_id={client_id}' \
-d 'client_secret={client_secret}'

Parameters with details:

Parameter
Type
Requirement
Description

token

String

Required

The access token or refresh token with the client to be revoked

token_type_hint

String

Required

To revoke an access token, use access_token as the value; to revoke a refresh token, use refresh_token as the value

client_id

String

Required

Client ID registered with digiRunner

client_secret

String

Optional

Scenario I. Higher-Security (Client Password Required)

Client Password registered with digiRunner

Scenario II. PKCE + Public Client (Client Password Not Required)

When the Public Client (With PKCE) option is selected in digiRunner's OAuth grant type, the parameter is not required.

Example of Successful Response

Example:

{
"code": "token_revoke_success",
"message": "access token revoke success, jti: 813a1d99-8a72-40a6-bf42-e26df6eadcb0"
}

Parameters with details:

Parameter
Type
Description

code

String

Custom response code for successful revocation, currently defined as two types:

token_revoke_success, the successful token revocation for this session.

token_already_revoked, the token has already been revoked.

message

String

Details for this successful revocation code

Example of Error Response

If the client password is incorrect, a 401 Unauthorized HTTP status code and JSON response will be returned.

Example:

{
"timestamp": "1685332432791",
"status": 401,
"error": "Unauthorized",
"message": "The client account or password is incorrect.clientId: tspldapclient",
"path": "/oauth/revocation"
}

Token Introspection

Verify the legitimacy of the access token or refresh token.

Example request:

curl -v -X POST https://{digiRunner_DOMAIN}/oauth/introspection \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'token={access_token}' \
-d 'token_type_hint=access_token' \
-d 'client_id={client_id}' \
-d 'client_secret={client_secret}'

Parameters with details:

Parameter
Type
Requirement
Description

token

String

Required

Token to be introspected

token_type_hint

String

Required

Specifies which type of token to introspect:

To introspect an access token, use access_token as the value; to introspect a refresh token, use refresh_token as the value

client_id

String

Required

Client ID registered with digiRunner

client_secret

String

Optional

Scenario I. Higher-Security (Client Password Required)

Client Password registered with digiRunner

Scenario II. PKCE + Public Client (Client Password Not Required)

When the Public Client (With PKCE) option is selected in digiRunner's OAuth grant type, the parameter is not required.

Example of Successful Response

Example:

{
"active": true,
"scope": "openid email profile 2000000086 2000000088",
"client_id": "tspldapclient",
"username": "Tsp Lee",
"token_type": "access_token",
"exp": 1685513177,
"iat": 1685426777,
"nbf": 1685426777,
"sub": "tspldapuser",
"aud": "YWRtaW5BUEk",
"iss": "https://10.20.30.88:18442/dgrv4/ssotoken/LDAP",
"jti": "882207db-4f84-433c-9508-1e1fb077ae13"
}

Parameters with details:

Parameter
Type
Description

active

Boolean

Indicates whether the token was issued by digiRunner, hasn't been revoked by the resource owner, and is still within its valid period. Returns true or false.

scope

String

Specifies the range of resources that the access token is granted permission to access

client_id

String

Use client_id as the value for OAuth

username

String

Identifies the user who authorized this token, such as an alias on the application

token_type

String

Indicates the type of the token, such as access_token or refresh_token

exp

Number

Token expiration time, an integer indicating the seconds since 1970-01-01T00:00:00Z UTC

iat

Number

Token issuance time by the OAuth Server, an integer indicating the seconds since 1970-01-01T00:00:00Z UTC when the token is issued by the OAuth Server.

nbf

Number

Token invalid time, an integer indicating the seconds since 1970-01-01T00:00:00Z UTC before the token becomes valid

sub

String

Identifies the user who authorized the token

aud

String

Indicates the audience intended to use the token

iss

String

Indicates the authorization server issuing the token

jti

String

Unique ID of this token, such as a UUID used when storing the token in a database to prevent replay attacks

Example of Error Response

If the client password is incorrect, a 401 Unauthorized HTTP status code and JSON response will be returned.

Example:

{
"timestamp": "1685332598344",
"status": 401,
"error": "Unauthorized",
"message": "The client account or password is incorrect. clientId: tspldapclient",
"path": "/oauth/introspection"
}