OpenID Connect (OIDC) Mode
Was this helpful?
Was this helpful?
Once the user completes authentication and authorization, the authorization code and state will be sent to the Default Redirect URL (callback).
When using a Public Client, select Public Client (With PKCE) in the OAuth grant type* field. The PKCE feature is applicable regardless of whether this option is selected. However, selecting Public Client (With PKCE) allows for the omission of a client password, as PKCE is required for a Public Client.
The PKCE specification adds parameters such as code_challenge_method, code_challenge, and code_verifier to verify that the request origin is consistent, allowing authorization to be completed without a client password. Although the process becomes more complex, it is one of the most secure modes available.
Initiate the process of authenticating LDAP/AD users and authorizing your application using the digiRunner platform. When the user clicks Login, they will be redirected to the authorization URL.
Example URL:
You can send the following parameters to the authorization URL.
response_type
String
Required
code, a fixed value
client_id
String
Required
Client ID registered with digiRunner
scope
String
Required
OIDC access scope; if there are multiple, separate them with "%20"
redirect_uri
String
Required
Redirect URL (callback) registered by the client with digiRunner
state
String
Required
Random code, a unique alphanumeric string used to prevent cross-site request forgery (CSRF) attacks. Your application should generate a random value, such as a UUID, for each login session.
code_challenge
String
Optional
Required only when using PKCE authentication.
KADwy…, a random string with a length of 43~128 characters, with the string as code_verifier, calculate code_challenge with SHA256 and Base64URL Encode: code_challenge = Base64URL Encode(SHA256(code_verifier))
Example:
code_verifier: B7gB0cY1C58ecNJ2J-231Ep-NmXgghAzgZg9nXu-vDo
code_challenge: Jhlf18b9aDFC5hkgQy3_MO1MznyS7kqMi32wELbhdos
code_challenge_method
String
Optional
Required only when using PKCE authentication.
S256, a fixed value
After completing the authentication and authorization process, the user will be redirected to the Redirect URL (callback). If the user has granted permission to access your application, an authorization code will be returned.If the user has not authorized access to your application, an error response will be returned.
When the user successfully completes the authentication and authorization steps,they will be redirected to the Redirect URL (callback) with the following parameters.
Example URL of the redirect target:
Parameters with details:
code
String
Authorization code for acquiring the access token; valid once for 10 minutes
state
String
If the request includes the state parameter, the same value should appear in the response. The application must verify if the state value in the request matches the one in the response.
If the user declines to grant permissions to your application request, they will be redirected to the Redirect URL (callback) with the following parameters.
Example URL of the redirect target:
Parameters with details:
rtn_code
String
Error code (Types as shown in the table below)
msg
String
Error message. TSP must use Base64URL Decode to obtain the error message, assisting developers in identifying specific error messages for authentication error reasons. This section contains most of the information about why the error occurred.
error
Disallowed application requesting an authorization code
User account or password error, or other errors
cancel
Resource owner denied consent
User pressed cancel on the consent screen
Example request:
Parameters with details:
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 using PKCE and 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
authorization_code, a fixed value used when making API calls
code
String
Required
Authorization code, a unique value that changes every time
redirect_uri
String
Required
Redirect URL (callback) registered by the client with digiRunner, for verification purposes
code_verifier
String
Optional
Required only when using PKCE authentication.
The code_verifier generated from the previous authorization request (/authorization).
Example:
code_verifier: B7gB0cY1C58ecNJ2J-231Ep-NmXgghAzgZg9nXu-vDo
code_challenge: Jhlf18b9aDFC5hkgQy3_MO1MznyS7kqMi32wELbhdos
Example of successful response:
access_token
String
Access token (JWT)
expires_in
Number
Time duration (unit: seconds) before the access token expires
jti
String
Access token ID
node
Number
Identifier compatible with digiRunner v3
refresh_token
String
Refresh token (JWT), used to obtain a new access token
scope
String
Permissions granted by the user
stime
Number
Start time of the access token issuance (unit: milliseconds).
token_type
String
Bearer token
idp_type
String
LDAP
id_token
String
ID token (JWT), which includes information about the user; this field is returned only when the scope specifies OpenID, email, or profile.
After user authentication is completed, the user will receive a response containing the access token and refresh token. The jti and idp_type values of the access token will be recorded in the browser's cookie.
When the user close the browser without logging out and later re-enter the TSP webpage, he can use cookies to obtain a new access token. This allows the user to access the TSP system without having to log in again.
Example request:
Parameters with details:
idp_type
String
Required
LDAP, the value of idp_type recorded in the browser cookie
jti
String
Required
Value of the access token’s jti recorded in the browser cookie
Example of successful response:
If the jti (access token ID) corresponds to an expired refresh token, a 401 Unauthorized HTTP status code and JSON response will be returned.
Example of error response:
After obtaining the access token issued by digiRunner, TSP can utilize the associated permissions to call APIs registered in digiRunner.
Example request:
Parameters with details:
access_token
String
Required
Access token (JWT)
Example request:
Parameters with details:
id_token
String
Required
ID token (JWT)
access_token
String
Required
Access token (JWT)
Using the methods mentioned above or invoking an API to verify the received ID token for its legitimacy and obtain the user's personal information and email.
Example request:
Parameters with details:
id_token
String
Required
ID token (JWT)
Example of successful response:
Parameters with details:
iss
String
Required
Issuer of the ID token
sub
String
Required
User Name
aud
String
Required
digiRunner's client ID
exp
Number
Required
Expiration date of the ID token
iat
Number
Required
Time of ID token generation
name
String
Optional
User's display name If the profile scope is not specified in the authorization request, it will not be included.
picture
String
Optional
User's profile picture URL If the profile scope is not specified in the authorization request, it will not be included.
email
String
Optional
User's email address If the email scope is not specified in the authorization request, it will not be included.
If the ID token has expired, a 400 Bad Request HTTP status code and JSON response will be returned.
Example of error response:
The ID token is a JSON Web Token (JWT) containing user information. Attackers may attempt to forge ID tokens. When your backend server receives an ID token from digiRunner, you should verify the authenticity of the ID token. You can refer to the journal on TPIsoftware University, use or implement your own validator.
