[Singpass Login] Token Endpoint Trouble Shooting

Introduction

This guide aims to help you understand how to interact with the token endpoint and troubleshoot common issues you may encounter. Whether you're a developer or a system administrator, this guide will provide you with step-by-step instructions and explanations for each error message.

Table of Contents

1. Getting a Response from the Token Endpoint

2. Understanding Request Structure

3. Common Error Messages

   • "invalid_client" with Missing or Invalid Claims

   • "invalid_client" with Signature Issues

   • "No valid encryption JWK"

   • "invalid_grant"

   • "CLIENT_SIDE_ERROR"

   • "unsupported_grant_type"

   • "SERVER_SIDE_ERROR"

1. Getting a Response from the Token Endpoint

How to Make a Request

• Create a POST/CURL request.

• Refer to the API specifications for the correct POST/CURL request structure.

Example Request

curl -X POST "https://token-endpoint-url" -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=YOUR_JWT_ASSERTION&client_id=YOUR_CLIENT_ID&grant_type=authorization_code&redirect_uri=https://www.example.com/singpass-login/callback&code=YOUR_AUTH_CODE"

2. Understanding Request Structure

• The parameters in the request are separated by &.

• The order of the parameters does not matter.

Required Parameters:

3. Common Error Messages

"invalid_client" with Missing or Invalid Claims

Error Description:
The client_assertion has missing or invalid claims.

Possible Causes:

• Token is expired

• Server time is not synchronized

• Incorrect client assertion structure

Troubleshooting Steps:

1. Verify your client assertion using jwt.io.

2. Ensure all required claims are present and valid.

"invalid_client" with Signature Issues

Error Description:
The client_assertion could not be validated against known signing keys.

Possible Causes:

• JWT is not signed correctly

• Mismatched "kid" value

• Incorrect algorithm

Troubleshooting Steps:

1. Use jwt.io to verify the signature.

2. Ensure the JWT is signed with the correct private key.

"No valid encryption JWK"

Error Description:
The JWKS URL does not have a valid encryption key.

Troubleshooting Steps:

1. Ensure your encryption key meets the requirements.

"invalid_grant"

Error Description:
The grant requested is not valid.

Possible Causes:

• Old or expired authCode

• Incorrect grant_type

• Incorrect request parameters

Troubleshooting Steps:

1. Generate a new authCode.

2. Check for encoding issues.

3. Verify request parameters.

"CLIENT_SIDE_ERROR"

Error Description:
There is an error with the request payload to the token endpoint.

Possible Causes:

• Incorrect POST request format

Troubleshooting Steps:

1. Ensure the POST request follows the specified format.

"unsupported_grant_type"

Error Description:
The grant type is not supported.

Possible Causes:

• Incorrect grant_type

• Incorrect request parameters

Troubleshooting Steps:

1. Ensure grant_type is set to authorization_code.

2. Verify request parameters.

"SERVER_SIDE_ERROR"

Error Description:
An unexpected error occurred.

Possible Causes:

• JWKS URL issues

• SSL certificate chain issues

• Domain not whitelisted

Troubleshooting Steps:

1. Check JWKS URL.

2. Verify SSL certificate chain.

3. Ensure domain is whitelisted.

Conclusion

This guide should help you troubleshoot most issues you might encounter with the token endpoint. If you're still facing problems, consider using a step-by-step Postman guide to generate your response.

Feel free to bookmark this guide for future reference. Good luck!