.well-known Endpoints

OpenID discovery endpoint

Responses from this endpoint can and should be cached for at least 1 hour, and NOT retrieved for each OIDC/OAuth2 operation. Cache-Control headers on the response indicate a possible policy.

Curl request

$ curl 'https://stg-id.singpass.gov.sg/.well-known/openid-configuration' -i -X GET \
    -H 'Accept: application/json'

HTTP request

GET /.well-known/openid-configuration HTTP/1.1
Accept: application/json
Host: stg-id.singpass.gov.sg

HTTP response

HTTP/1.1 200 OK
Cache-Control: max-age=21600, must-revalidate, no-transform, public
X-XSS-Protection: 0
X-Frame-Options: DENY
Date: Fri, 14 Feb 2025 01:38:28 GMT
Connection: keep-alive
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
Transfer-Encoding: chunked
Content-Type: application/json
Content-Length: 1349

{
  "issuer" : "https://stg-id.singpass.gov.sg",
  "authorization_endpoint" : "https://stg-id.singpass.gov.sg/auth",
  "jwks_uri" : "https://stg-id.singpass.gov.sg/.well-known/keys",
  "response_types_supported" : [ "code" ],
  "scopes_supported" : [ "openid" ],
  "subject_types_supported" : [ "public" ],
  "claims_supported" : [ "nonce", "aud", "iss", "sub", "exp", "iat" ],
  "grant_types_supported" : [ "authorization_code", "urn:openid:params:grant-type:ciba" ],
  "token_endpoint" : "https://stg-id.singpass.gov.sg/token",
  "token_endpoint_auth_methods_supported" : [ "private_key_jwt" ],
  "token_endpoint_auth_signing_alg_values_supported" : [ "ES256", "ES384", "ES512" ],
  "id_token_signing_alg_values_supported" : [ "ES256" ],
  "id_token_encryption_alg_values_supported" : [ "ECDH-ES+A256KW", "ECDH-ES+A192KW", "ECDH-ES+A128KW" ],
  "id_token_encryption_enc_values_supported" : [ "A256CBC-HS512" ],
  "backchannel_authentication_endpoint" : "https://stg-id.singpass.gov.sg/bc-auth",
  "backchannel_token_delivery_modes_supported" : [ "poll" ],
  "userinfo_endpoint" : "https://stg-id.singpass.gov.sg/userinfo",
  "userinfo_signing_alg_values_supported" : [ "ES256" ],
  "userinfo_encryption_alg_values_supported" : [ "ECDH-ES+A256KW", "ECDH-ES+A192KW", "ECDH-ES+A128KW" ],
  "userinfo_encryption_enc_values_supported" : [ "A256GCM" ]
}

HTTPie request

$ http GET 'https://stg-id.singpass.gov.sg/.well-known/openid-configuration' \
    'Accept:application/json'

Request body

Response body

{
  "issuer" : "https://stg-id.singpass.gov.sg",
  "authorization_endpoint" : "https://stg-id.singpass.gov.sg/auth",
  "jwks_uri" : "https://stg-id.singpass.gov.sg/.well-known/keys",
  "response_types_supported" : [ "code" ],
  "scopes_supported" : [ "openid" ],
  "subject_types_supported" : [ "public" ],
  "claims_supported" : [ "nonce", "aud", "iss", "sub", "exp", "iat" ],
  "grant_types_supported" : [ "authorization_code", "urn:openid:params:grant-type:ciba" ],
  "token_endpoint" : "https://stg-id.singpass.gov.sg/token",
  "token_endpoint_auth_methods_supported" : [ "private_key_jwt" ],
  "token_endpoint_auth_signing_alg_values_supported" : [ "ES256", "ES384", "ES512" ],
  "id_token_signing_alg_values_supported" : [ "ES256" ],
  "id_token_encryption_alg_values_supported" : [ "ECDH-ES+A256KW", "ECDH-ES+A192KW", "ECDH-ES+A128KW" ],
  "id_token_encryption_enc_values_supported" : [ "A256CBC-HS512" ],
  "backchannel_authentication_endpoint" : "https://stg-id.singpass.gov.sg/bc-auth",
  "backchannel_token_delivery_modes_supported" : [ "poll" ],
  "userinfo_endpoint" : "https://stg-id.singpass.gov.sg/userinfo",
  "userinfo_signing_alg_values_supported" : [ "ES256" ],
  "userinfo_encryption_alg_values_supported" : [ "ECDH-ES+A256KW", "ECDH-ES+A192KW", "ECDH-ES+A128KW" ],
  "userinfo_encryption_enc_values_supported" : [ "A256GCM" ]
}

Response fields

Path

Type

Description

issuer

String

URL (identity) of the issuer

authorization_endpoint

String

URL of the OP’s OAuth 2.0 Authorization Endpoint

jwks_uri

String

URL of the OP’s JSON Web Key Set

response_types_supported

Array

JSON array containing a list of the OAuth 2.0 response_type values that OP supports

scopes_supported

Array

JSON array containing a list of the OAuth 2.0 scope values that OP supports

subject_types_supported

Array

JSON array containing a list of the Subject Identifier types that this OP supports

claims_supported

Array

JSON array containing a list of the Claim Names of the Claims that the OpenID Provider MAY be able to supply values for

grant_types_supported

Array

JSON array containing a list of the OAuth 2.0 Grant Type values that this OP supports.

token_endpoint

String

URL of the OP’s OAuth 2.0 Token Endpoint. This contains the signing key(s) the RP uses to validate signatures from the OP.

token_endpoint_auth_methods_supported

Array

JSON array containing a list of Client Authentication methods supported by this Token Endpoint.

token_endpoint_auth_signing_alg_values_supported

Array

JSON array containing a list of the JWS signing algorithms (alg values) supported by the Token Endpoint for the signature on the JWT used to authenticate the Client at the Token Endpoint for the private_key_jwt authentication methods

id_token_signing_alg_values_supported

Array

JSON array containing a list of the JWS signing algorithms (alg values) supported by the OP for the ID Token to encode the Claims in a JWT.

id_token_encryption_alg_values_supported

Array

JSON array containing a list of the JWE encryption algorithms (alg values) supported by the OP for the ID Token to encode the Claims in a JWT.

id_token_encryption_enc_values_supported

Array

JSON array containing a list of the JWE encryption algorithms (enc values) supported by the OP for the ID Token to encode the Claims in a JWT.

backchannel_token_delivery_modes_supported

Array

JSON array containing supported backchannel delivery modes

backchannel_authentication_endpoint

String

URL of the OP’s Backchannel Authentication Endpoint

userinfo_endpoint

String

URL of the OP’s UserInfo Endpoint

userinfo_signing_alg_values_supported

Array

JSON array containing a list of the JWS signing algorithms (alg values) supported by the UserInfo Endpoint to encode the Claims in a JWT.

userinfo_encryption_alg_values_supported

Array

JSON array containing a list of the JWE encryption algorithms (alg values) supported by the UserInfo Endpoint to encode the Claims in a JWT.

userinfo_encryption_enc_values_supported

Array

JSON array containing a list of the JWE encryption algorithms (enc values) supported by the UserInfo Endpoint to encode the Claims in a JWT.

JWKS endpoint

NDI signs all JWTs issued during the authentication process using its ASP signing key. Integrating parties can validate the JWT signatures by acquiring the signing public key from a JSON Web Key Set (JWKS) endpoint.

This endpoint will return one or more public keys in JSON Web Key (JWK) form. The correct JWK to use for signature validation will have its use attribute as sig (to indicate that it is a signing key), and its kid value should match the one found in the JWT under validation.

Public keys returned from this endpoint could be in random sequence or rotated for security enhancement. For more information, please refer to Caching and key rotation section.

Curl request

$ curl 'https://stg-id.singpass.gov.sg/.well-known/keys' -i -X GET \
    -H 'Accept: application/json'

HTTP request

GET /.well-known/keys HTTP/1.1
Accept: application/json
Host: stg-id.singpass.gov.sg

HTTP response

HTTP/1.1 200 OK
Cache-Control: max-age=21600, must-revalidate, no-transform, public
X-XSS-Protection: 0
X-Frame-Options: DENY
Date: Fri, 14 Feb 2025 01:38:28 GMT
Connection: keep-alive
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
Content-Type: application/json
Content-Length: 697

{
  "keys" : [ {
    "kty" : "EC",
    "use" : "sig",
    "crv" : "P-256",
    "kid" : "eckey-test",
    "x" : "Nf4-Nc2_hC5pg1Pr274P6YN1cZNZHZRUm8sccBYQBFU",
    "y" : "I2whYvPaxHocMfJ5ob67Ow9uk_TksTCQQ_x-DN9oMeo"
  }, {
    "kty" : "EC",
    "use" : "sig",
    "crv" : "P-256",
    "kid" : "eckey-test-secondary",
    "x" : "qfdyc_f2hxS_4-76Z9WH9itB_S49Q3vsoJTxOBJpXmQ",
    "y" : "gSdCGVcqx4_l8hgKh_nJAOn2F52tDKyvQPLfDZoi1bI"
  }, {
    "kty" : "EC",
    "use" : "sig",
    "crv" : "P-256",
    "kid" : "alias/test-sp-auth-api-id-token-signing-key-kms-asymmetric-key-alias",
    "x" : "1TsrYH0vsifCBY2ZzeXHm-e53jndsoRzaiBRuAyMd8o",
    "y" : "sdMKEjilloz3eUH8dBI_d_gF07TSJzhr3tYa_qLdLqw"
  } ]
}

HTTPie request

$ http GET 'https://stg-id.singpass.gov.sg/.well-known/keys' \
    'Accept:application/json'

Request body

Response body

{
  "keys" : [ {
    "kty" : "EC",
    "use" : "sig",
    "crv" : "P-256",
    "kid" : "eckey-test",
    "x" : "Nf4-Nc2_hC5pg1Pr274P6YN1cZNZHZRUm8sccBYQBFU",
    "y" : "I2whYvPaxHocMfJ5ob67Ow9uk_TksTCQQ_x-DN9oMeo"
  }, {
    "kty" : "EC",
    "use" : "sig",
    "crv" : "P-256",
    "kid" : "eckey-test-secondary",
    "x" : "qfdyc_f2hxS_4-76Z9WH9itB_S49Q3vsoJTxOBJpXmQ",
    "y" : "gSdCGVcqx4_l8hgKh_nJAOn2F52tDKyvQPLfDZoi1bI"
  }, {
    "kty" : "EC",
    "use" : "sig",
    "crv" : "P-256",
    "kid" : "alias/test-sp-auth-api-id-token-signing-key-kms-asymmetric-key-alias",
    "x" : "1TsrYH0vsifCBY2ZzeXHm-e53jndsoRzaiBRuAyMd8o",
    "y" : "sdMKEjilloz3eUH8dBI_d_gF07TSJzhr3tYa_qLdLqw"
  } ]
}

Caching and key rotation

Important

Responses from this endpoint, or individual keys from inside the JWKS can and should be cached for at least 1 hour, and NOT retrieved for each JWT validation. Cache-Control headers on the response indicate a possible policy.

For varying reasons, keys used for signing can and will be rotated/changed with no defined schedule, and at the full discretion of NDI. When a key rotation happens, the new key will be available from the JWKS endpoint and will have a different kid value. The new kid value will be reflected in all the new JWTs signed by NDI. In such cases, cached copies of NDI public keys must be refreshed by re-invoking the JWKS endpoint.

If the validation of the NDI signature fails, re-fetch from the JWKS endpoint once for that validation.

Please read through the list of DON’Ts below:

Do not assume the position of a signing key among the list of the returned keys.
Do not validate NDI signatures using a hardcoded public key OR kid. Always determine the correct key (for signature verification) by inspecting the kid from the JWS header, and use it to retrieve the public key from our JWKS endpoint.
Do not cache only 1 key. Caching should be done for the entire JWKS.

PreviousToken Endpoint NextStaging and Production Endpoints

Last updated 11 months ago

Was this helpful?

hashtagOpenID discovery endpoint

hashtagCurl request

hashtagHTTP request

hashtagHTTP response

hashtagHTTPie request

hashtagRequest body

hashtagResponse body

hashtagResponse fields

hashtagJWKS endpoint

hashtagCurl request

hashtagHTTP request

hashtagHTTP response

hashtagHTTPie request

hashtagRequest body

hashtagResponse body

hashtagCaching and key rotation

OpenID discovery endpoint

Curl request

HTTP request

HTTP response

HTTPie request

Request body

Response body

Response fields

JWKS endpoint

Curl request

HTTP request

HTTP response

HTTPie request

Request body

Response body

Caching and key rotation