> For the complete documentation index, see [llms.txt](https://docs.tpi.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tpi.dev/api-integration-guide/using-token-for-authentication-and-authorization/openid-connect-oidc-mode.md). # OpenID Connect (OIDC) Mode ### **Workflow Overview** #### **Higher-Security Process (Client Password Required)** ![](https://content.gitbook.com/content/0choIC1BbdPOkKWOYGgk/blobs/RIBtu6rmAvmVMz4l6Kfh/0.png) ![](https://content.gitbook.com/content/0choIC1BbdPOkKWOYGgk/blobs/pJinbLH1SdhkGPrOYjkh/1.png) #### **PKCE + Public Client Process (Client Password Not Required)** ![](https://content.gitbook.com/content/0choIC1BbdPOkKWOYGgk/blobs/kygsDn8nFP0iSjZMa9U8/2.png) ![](https://content.gitbook.com/content/0choIC1BbdPOkKWOYGgk/blobs/DKn17izFCZa4sNxSI4Xl/3.png) ![](https://content.gitbook.com/content/0choIC1BbdPOkKWOYGgk/blobs/6Sfzgb4qpheHlZ4F6aJ7/4.png) ### **Setting up Callback** Once the user completes authentication and authorization, the authorization code and state will be sent to the **Default Redirect URL** (callback). ![](https://content.gitbook.com/content/0choIC1BbdPOkKWOYGgk/blobs/22aNfODidVnRdZR8EzyV/5.png) 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. ![](https://content.gitbook.com/content/0choIC1BbdPOkKWOYGgk/blobs/eiNi16ZjLY0SJWmv7FWN/6.png) ### **Initiating Authorization Requests and Validating Users** 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: ``` https://{digiRunner_DOMAIN}/dgrv4/ssotoken/gtwidp/LDAP/authorization? response_type=code&client_id= {client_id}&scope=openid%20profile%20email&redirect_uri= https://example.com/callback&state={state}&code_challenge= {code_challenge}&code_challenge_method=S256 ``` You can send the following parameters to the authorization URL.

Parameter	Type	Requirement	Description
`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

### **User Login with LDAP/AD**

### **User Authorization**

### **Receiving Authorization Code or Error Response** 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. #### **Receiving Authorization Code** 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: ``` https://example.com/callback?code={code}&state={state} ``` Parameters with details:

Parameter	Type	Description
`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.

#### **Receiving Error 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: ``` https://example.com/callback?rtn_code=cancel&msg=VXNlciBwcmVzc2VzIGNhbmNlbA ``` Parameters with details:

Parameter	Type	Description
`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 Code	Description	User Action
`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

### **Obtaining Access Token / Refresh Token / ID 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=authorization_code' \ -d 'code={code}' \ -d 'redirect_uri=https://example.com/callback' -d 'code_verifier={code_verifier}' ``` 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 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`

Parameter	Type	Description
`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.

### **Token Renewal with Cookie Token** 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: ``` curl -v -X POST https://{digiRunner_DOMAIN}/oauth/token \ -H 'Accept: application/json' \ -H 'Cookie: idp_type=LDAP; jti={jti}' ``` Parameters with details:

Parameter	Type	Requirement	Description
`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: ``` { "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJub2RlIjoiZXhlY3V0b3IxIiwiYXVkIjpbIllXUnRhVzVCVUVrIl0sInVzZXJfbmFtZSI6Im1pbmlsZGFwIiwic2NvcGUiOlsib3BlbmlkIiwiZW1haWwiLCJwcm9maWxlIiwiMjAwMDAwMDA4NiIsIjIwMDAwMDAwODgiXSwic3RpbWUiOj...", "expires_in": 1799, "jti": "815f60d2-9c1d-4402-bbf0-60df49e94bef", "node": "executor1", "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJub2RlIjoiZXhlY3V0b3IxIiwiYXVkIjpbIllXUnRhVzVCVUVrIl0sInVzZXJfbmFtZSI6Im1pbmlsZGFwIiwic2NvcGUiOlsib3BlbmlkIiwiZW1haWwiLCJwcm9maWxlIiwiMjAwMDAwMDA4NiIsIjIwMDAwMDAwODgiXSwiYXRpIjoiOD...", "scope": "openid email profile 2000000086 2000000088", "stime": 1684824569848, "token_type": "bearer", "idp_type": "LDAP", "id_token": "eyJraWQiOiJmODE4ZDk3MS04ZGJiLTQ3YjMtOTI5MS1mNDJiMWVhMDZlMTgiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiRzQ3dEQ2WVd5X0RGaWNyZzZjc200dyIsImF1ZCI6Im1pbmlsZGFwY2xpZW50Iiwic3ViIjoibWluaWxkYXAiLCJpc3MiOiJodHRwczovLzEw..." ``` 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: ``` { "error": "invalid_token", "error_description": "Refresh token expired, exp: 1684910969, expired at: 2023/05/17 09:47:31.000" } ``` ### **Calling APIs Registered in digiRunner with Access Token** After obtaining the access token issued by digiRunner, TSP can utilize the associated permissions to call APIs registered in digiRunner. Example request: ``` curl -v -X POST 'https://{digiRunner_DOMAIN}/tsmpc/tspTest/postApi' \ -H 'Authorization: Bearer {access_token}' ``` Parameters with details:

Parameter	Type	Requirement	Description
`access_token`	String	Required	Access token (JWT)

### **Calling APIs Registered in digiRunner with ID Token** Example request: ``` curl -v -X POST 'https://{digiRunner_DOMAIN}/tsmpc/tspTest/postApi' \ -H 'ID-Token: {id_token}' \ -H 'Authorization: Bearer {access_token}' ``` Parameters with details:

Parameter	Type	Requirement	Description
`id_token`	String	Required	ID token (JWT)
`access_token`	String	Required	Access token (JWT)

#### **Verifying ID Token through Custom Implementation** 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 [How to Apply ID Token (ID Token 如何應用)](https://www.tpisoftware.com/tpu/articleDetails/2919) on TPIsoftware University, use [JWT libraries](https://jwt.io/#libraries-io) or implement your own validator. #### **Verifying ID Token by Calling an API** 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: ``` curl -v -X POST 'https://{digiRunner_DOMAIN}/dgrv4/ssotoken/gtwidp/verify' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'id_token={id_token}' ``` Parameters with details:

Parameter	Type	Requirement	Description
`id_token`	String	Required	ID token (JWT)

Example of successful response: ``` { "iss": "https://10.20.30.88:18442/dgrv4/ssotoken/LDAP", "sub": "tspldapuser", "aud": "tspldapclient", "exp": 1686555619, "iat": 1686555019, "name": "Tsp Lee", "email": "tsp.lee@tpisoftware.com" } ``` Parameters with details:

Parameter	Type	Requirement	Description
`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: ``` { "error": "invalid_request", "error_description": "Expired JWT" } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.tpi.dev/api-integration-guide/using-token-for-authentication-and-authorization/openid-connect-oidc-mode.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.