4. Userinfo Endpoint
The Userinfo Endpoint allows Relying Parties (RPs) to retrieve detailed information about the authenticated Entity and Acting User. These details are not included in the ID Token and must be fetched explicitly after authentication.
This is a Protected Resource, requiring a valid Access Token (obtained from the Token Endpoint) for access.
Currently, this endpoint primarily returns the user's Authorization Data (e.g., roles, authorized transactions), similar to the Legacy Authorization Info Endpoint.
Request
To obtain additional entity or user information, send a GET request to the Userinfo Endpoint URL obtained from the OpenID Discovery Endpoint (userinfo_endpoint).
Corppass supports both GET and POST methods for the Userinfo Endpoint.
The OIDC Specification (Section 5.3.2) recommends using the GET method.
Sample GET Request (Recommended)
GET /userinfo HTTP/1.1
Authorization: DPoP eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
DPoP: <signed-dpop-proof-jwt>Sample POST Request
Request body is not required and will be ignored for POST request.
POST /userinfo HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Authorization: DPoP eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
DPoP: <signed-dpop-proof-jwt>Request Headers
Content-Type
POST only
Indicates the encoding format of the request body.
Validation:
Must be set to
application/x-www-form-urlencoded; charset=utf-8.
Authorization
Yes
Carries the Access Token issued at the Token Endpoint, using the DPoP scheme instead of the typical Bearer scheme.
Example:
Authorization: DPoP <Access-Token>
DPoP
Yes
DPoP Proof JWT. A signed proof-of-possession JWT bound to the Access Token.
Validation:
This proof must include the
ath(Access Token Hash) claim. This ensures the proof is cryptographically linked to the specific Access Token used in the request, preventing token misuse.
Refer to the Demonstrating Proof of Possession section for more details.
Success Response
The Userinfo Endpoint returns a response in the form of a JSON Web Encryption (JWE) object, encrypted using the client's public encryption key configured in their JWKS object / JWKS endpoint.
Inside the encrypted payload lies the Signed JWT (JWS), signed using Corppass' private signing key. Refer to ID Token section for the decryption steps.
Response Structure (Decoded Payload)
The following table details the claims found in the decoded JWS payload:
aud
String
Audience. The client ID of the Relying Party for whom this token is intended.
iss
String
Issuer. The URL of the Corppass server that issued the token.
iat
Number
Issued At. The time the JWT was issued, expressed as a UNIX timestamp.
exp
Number
Expiration Time. The expiration time of the JWT.
Value is set to 10 minutes from iat.
sub
String
Subject. The unique identifier for the authenticated user (in this case, we return Client ID).
auth_info
JSON
Authorization information assigned to the user.
Refer to the Auth Info section for more details.
Required scope: authinfo
tp_auth_info
JSON
Third-party authorization information assigned to the user.
Refer to the Third-party Auth Info section for more details.
Required scope: tpauthinfo
Sample Response (Decoded Payload)
Error Response
If the Access Token is invalid, expired, or the DPoP proof fails, Corppass returns a JSON response containing an error code and description.
Response Header
The response will always include the WWW-Authenticate header when the access token is missing or invalid. For DPoP-bound tokens, this header specifically indicates issues with the token or its associated proof.
Response Body
error
String
A standardised error code identifying the type of error that occurred.
See Error Codes below for a complete list of possible values.
error_description
String
A human-readable text description providing additional details about the error.
Error Codes
invalid_request
400
This may be due to one of the following:
A required request parameter is missing.
A request parameter is malformed or does not meet the expected format.
The client’s JWKS endpoint is not reachable.
The JWKS object is empty or the encryption key is not available.
Please ensure that:
All required parameters are provided and correctly formatted.
Your JWKS endpoint is accessible and returns a valid key set that complies with the required specification.
invalid_client
401
This may be due to one of the following:
Missing client credential
Invalid client credential
Expired client credential
Improperly formatted client credential or assertion (e.g., malformed JWT)
The client’s JWKS does not contain the required signing key
Please ensure that:
The client credential is present, valid, and not expired
Your JWKS endpoint is accessible and returns a valid key set that complies with the required specification.
invalid_token
401
Access token is expired, invalid, or not properly bound.
invalid_dpop_proof
401
This may due to the one of the following:
The DPoP proof is expired.
The DPoP proof is malformed.
The DPoP proof failed signature verification.
The DPoP proof contains missing or invalid required claims.
Please ensure that:
The DPoP proof is correctly structured and signed using the client's private key.
The DPoP proof complies with the required specification.
If the request lacks authentication altogether (e.g., no Authorization header or unsupported scheme), Corppass will return HTTP 401 without including any error code, description, or body.
This prevents revealing information about authentication requirements to unauthenticated or potentially malicious clients, as recommended by RFC 6750 Section 3.1.
Sample Response
Last updated