Version Control

Version	Date	Author	Comments

Version	Date	Author	Comments
3.0.0-draft2	Mar 3, 2023	Payments NZ API Working Group	Initial draft
3.0.0-rc1	May 5, 2023	@Nigel Somerfield	Baseline for release candidate 1
3.0.0	Nov 13, 2023	@Nigel Somerfield	Version 3.0.0 release

Introduction

In OpenID Connect and OAuth 2.0, an Authorisation Server publishes metadata that describes its supported capabilities. Authorisation Server metadata is constrained by the NZ Banking Data API Security Profile (this document).

Normative References

The following referenced documents are strongly recommended to be used in conjunction with this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies

OIDC Discovery: https://openid.net/specs/openid-connect-discovery-1_0.html
OIDC CIBA: https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html
IANA OAuth 2.0 Parameter Registry https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata
IANA Well-Known URIs:
RFC8414
RFC9101
RFC9126
JWT response for OAuth Token Introspection

Informative references

The following referenced documents may be useful to standards users:

OpenAPI method for documenting well-known endpoint https://swagger.io/docs/specification/authentication/openid-connect-discovery/

Table of metadata

The following table shows authorisation server metadata values that are published by API Providers in accordance with and . The URI at which the metadata is published is the API Provider’s authorisation server well-known end-point e.g (https://as.apiproivder.co.nz/oauth2/.well-known/openid-configuration). API Providers must publish this location on their API portal.

The items listed as mandatory are the minimum set to be published by API Provider Authorisation Servers.

Metadata Name	Metadata Description	Mandatory/Optional	Example	Required values	Notes	Reference

Metadata Name	Metadata Description	Mandatory/Optional	Example	Required values	Notes	Reference
`authorization_endpoint`	URL of the authorization server's authorization endpoint	Mandatory	https://as.apiprovider.co.nz/oauth2/authorize			[RFC8414, Section 2]
`backchannel_authentication_endpoint`	CIBA Backchannel Authentication Endpoint	Mandatory	https://as.apiprovider.co.nz/bc-authorize			[OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0, Section 4]
`backchannel_authentication_request_signing_alg_values_supported`	JSON array containing a list of the JWS signing algorithms supported for validation of signed CIBA authentication requests	Mandatory	[ "RS256", "ES256", "PS256" ]	[ "ES256", "PS256" ]		[OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0, Section 4]
`backchannel_token_delivery_modes_supported`	Supported CIBA authentication result delivery modes	Mandatory	[ "poll", "ping", "push" ]	[ "poll", "ping" ]		[OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0, Section 4]
`claim_types_supported`	JSON array containing a list of the Claim Types that the OpenID Provider supports	Optional	[ "normal", "aggregated" ]	[ "normal" ]		[OpenID Connect Discovery 1.0, Section 3]
`claims_locales_supported`	Languages and scripts supported for values in Claims being returned, represented as a JSON array of BCP 47 [RFC5646] language tag values	Optional	[ "en-nz", "mi" ]			[OpenID Connect Discovery 1.0, Section 3]
`claims_parameter_supported`	Boolean value specifying whether the OP supports use of the "claims" parameter	Mandatory		true		[OpenID Connect Discovery 1.0, Section 3]
`claims_supported`	JSON array containing a list of the Claim Names of the Claims that the OpenID Provider MAY be able to supply values for	Optional		[ "ConsentId" ]	Other claims may be included	[OpenID Connect Discovery 1.0, Section 3]
`code_challenge_methods_supported`	PKCE code challenge methods supported by this authorization server	Mandatory		[ "S256" ]	No other values supported	[RFC8414, Section 2]
`grant_types_supported`	JSON array containing a list of the OAuth 2.0 grant type values that this authorization server supports	Optional	[ "client_credentials", "authorization_code", "referesh_token", "urn:openid:params:grant-type:ciba" ]	[ "refresh_token", "client_credentials", "authorization_code", "urn:openid:params:grant-type:ciba" ]		[RFC8414, Section 2]
`id_token_encryption_alg_values_supported`	JSON array containing a list of the JWE "alg" values supported by the OP for the ID Token	Optional			Not supported in v3.0.0	[OpenID Connect Discovery 1.0, Section 3]
`id_token_encryption_enc_values_supported`	JSON array containing a list of the JWE "enc" values supported by the OP for the ID Token	Optional			Not supported in v3.0.0	[OpenID Connect Discovery 1.0, Section 3]
`id_token_signing_alg_values_supported`	JSON array containing a list of the JWS "alg" values supported by the OP for the ID Token	Mandatory		[ "ES256", "PS256" ]		[OpenID Connect Discovery 1.0, Section 3]
`introspection_encryption_alg_values_supported`	JSON array containing a list of algorithms supported by the authorization server for introspection response content key encryption (alg value).	Optional			Not supported in v3.0.0	[RFC-ietf-oauth-jwt-introspection-response-12, Section 7]
`introspection_encryption_enc_values_supported`	JSON array containing a list of algorithms supported by the authorization server for introspection response content encryption (enc value).	Optional			Not supported in v3.0.0	[RFC-ietf-oauth-jwt-introspection-response-12, Section 7]
`introspection_endpoint`	URL of the authorization server's OAuth 2.0 introspection endpoint	Mandatory	https://as.apiprovider.co.nz/oauth2/introspect			[RFC8414, Section 2]
`introspection_endpoint_auth_methods_supported`	JSON array containing a list of client authentication methods supported by this introspection endpoint	Mandatory		[ "private_key_jwt" ]		[RFC8414, Section 2]
`introspection_endpoint_auth_signing_alg_values_supported`	JSON array containing a list of the JWS signing algorithms supported by the introspection endpoint for the signature on the JWT used to authenticate the client at the introspection endpoint	Mandatory		[ "ES256", "PS256" ]		[RFC8414, Section 2]
`introspection_signing_alg_values_supported`	JSON array containing a list of algorithms supported by the authorization server for introspection response signing.	Optional				[RFC-ietf-oauth-jwt-introspection-response-12, Section 7]
`issuer`	Authorization server's issuer identifier URL	Mandatory	https://as.apiprovider.co.nz/issuer			[RFC8414, Section 2]
`jwks_uri`	URL of the authorization server's JWK Set document	Mandatory	https://as.apiprovider.co.nz/.well-known/jwks			[RFC8414, Section 2]
`mtls_endpoint_aliases`	JSON object containing alternative authorization server endpoints, which a client intending to do mutual TLS will use in preference to the conventional endpoints.	Optional	"mtls_endpoint_aliases": { "token_endpoint": "https://mtls.example.com/token", "revocation_endpoint": "https://mtls.example.com/revo", "introspection_endpoint": "https://mtls.example.com/introspect" }			[RFC8705, Section 5]
`op_policy_uri`	URL that the authorization server provides to the person registering the client to read about the authorization server's requirements on how the client can use the data provided by the authorization server	Optional				[RFC8414, Section 2]
`op_tos_uri`	URL that the authorization server provides to the person registering the client to read about the authorization server's terms of service	Optional				[RFC8414, Section 2]
`pushed_authorization_request_endpoint`	URL of the authorization server's pushed authorization request endpoint	Mandatory	https://as.apiprovider.co.nz/par			[RFC9126, Section 5]
`request_object_encryption_alg_values_supported`	JSON array containing a list of the JWE "alg" values supported by the OP for Request Objects	Optional			Not supported in v3.0.0	[OpenID Connect Discovery 1.0, Section 3]
`request_object_encryption_enc_values_supported`	JSON array containing a list of the JWE "enc" values supported by the OP for Request Objects	Optional			Not supported in v3.0.0	[OpenID Connect Discovery 1.0, Section 3]
`request_object_signing_alg_values_supported`	JSON array containing a list of the JWS "alg" values supported by the OP for Request Objects	Mandatory		[ "ES256", "PS256" ]		[OpenID Connect Discovery 1.0, Section 3]
`request_parameter_supported`	Boolean value specifying whether the OP supports use of the "request" parameter	Mandatory		true		[OpenID Connect Discovery 1.0, Section 3]
`request_uri_parameter_supported`	Boolean value specifying whether the OP supports use of the "request_uri" parameter	Mandatory		true		[OpenID Connect Discovery 1.0, Section 3]
`require_pushed_authorization_requests`	Indicates whether the authorization server accepts authorization requests only via PAR.	Optional			Required if not using hybrid flow	[RFC9126, Section 5]
`require_request_uri_registration`	Boolean value specifying whether the OP requires any "request_uri" values used to be pre-registered	Optional		false		[OpenID Connect Discovery 1.0, Section 3]
`require_signed_request_object`	Indicates where authorization request needs to be protected as Request Object and provided through either request or request_uri parameter.	Mandatory		true		[RFC9101, Section 10.5]
`response_modes_supported`	JSON array containing a list of the OAuth 2.0 "response_mode" values that this authorization server supports	Optional	[ "fragment", "jwt" ]	[ "jwt" ]	Required values depend on supported flows	[RFC8414, Section 2]
`response_types_supported`	JSON array containing a list of the OAuth 2.0 "response_type" values that this authorization server supports	Mandatory	[ "code", "code id_token" ]	[ "code" ]	May include hybrid flow	[RFC8414, Section 2]
`revocation_endpoint`	URL of the authorization server's OAuth 2.0 revocation endpoint	Optional				[RFC8414, Section 2]
`revocation_endpoint_auth_methods_supported`	JSON array containing a list of client authentication methods supported by this revocation endpoint	Optional				[RFC8414, Section 2]
`revocation_endpoint_auth_signing_alg_values_supported`	JSON array containing a list of the JWS signing algorithms supported by the revocation endpoint for the signature on the JWT used to authenticate the client at the revocation endpoint	Optional				[RFC8414, Section 2]
`scopes_supported`	JSON array containing a list of the OAuth 2.0 "scope" values that this authorization server supports	Mandatory	[ "openid", "accounts", "payments", "profile" ]	[ “openid”, “accounts”, “payments” ]	Authorisation servers that are re-used by API providers may have additional scopes	[RFC8414, Section 2]
`service_documentation`	URL of a page containing human-readable information that developers might want or need to know when using the authorization server	Optional				[RFC8414, Section 2]
`signed_metadata`	Signed JWT containing metadata values about the authorization server as claims	Optional				[RFC8414, Section 2.1]
`subject_types_supported`	JSON array containing a list of the Subject Identifier types that this OP supports	Mandatory		[ "pairwise" ]		[OpenID Connect Discovery 1.0, Section 3]
`tls_client_certificate_bound_access_tokens`	Indicates authorization server support for mutual-TLS client certificate-bound access tokens.	Mandatory		true		[RFC8705, Section 3.3]
`token_endpoint`	URL of the authorization server's token endpoint	Mandatory	https://as.apiprovider.co.nz/oauth2/token			[RFC8414, Section 2]
`token_endpoint_auth_methods_supported`	JSON array containing a list of client authentication methods supported by this token endpoint	Mandatory		[ "private_key_jwt" ]		[RFC8414, Section 2]
`token_endpoint_auth_signing_alg_values_supported`	JSON array containing a list of the JWS signing algorithms supported by the token endpoint for the signature on the JWT used to authenticate the client at the token endpoint	Mandatory		[ "ES256", "PS256" ]		[RFC8414, Section 2]
`ui_locales_supported`	Languages and scripts supported for the user interface, represented as a JSON array of language tag values from BCP 47 [RFC5646]	Optional				[RFC8414, Section 2]
`userinfo_encryption_alg_values_supported`	JSON array containing a list of the JWE "alg" values supported by the UserInfo Endpoint	Optional			Not supported in v3.0.0	[OpenID Connect Discovery 1.0, Section 3]
`userinfo_encryption_enc_values_supported`	JSON array containing a list of the JWE "enc" values supported by the UserInfo Endpoint	Optional			Not supported in v3.0.0	[OpenID Connect Discovery 1.0, Section 3]
`userinfo_endpoint`	URL of the OP's UserInfo Endpoint	Optional	https://as.apiprovider.co.nz/oauth2/userinfo			[OpenID Connect Discovery 1.0, Section 3]
`userinfo_signing_alg_values_supported`	JSON array containing a list of the JWS "alg" values supported by the UserInfo Endpoint	Optional	[ "ES256", "PS256" ]			[OpenID Connect Discovery 1.0, Section 3]

Example

The following is a non-normative example of authorisation server metadata:

{
    "authorization_endpoint": "https://as.apiprovider.co.nz/oauth2/authorize",
    "backchannel_authentication_endpoint": "https://as.apiprovider.co.nz/ciba/bc-authorize",
    "backchannel_authentication_request_signing_alg_values_supported": [
        "ES256",
        "PS256"
    ],
    "backchannel_token_delivery_modes_supported": [
        "poll",
        "ping"
    ],
    "backchannel_user_code_parameter_supported": false,
    "claim_types_supported": [
        "normal"
    ],
    "claims_locales_supported": [
        "en-nz",
        "mi"
    ],
    "claims_parameter_supported": true,
    "claims_supported": [
        "sub",
        "auth_time",
        "ConsentId"
    ],
    "code_challenge_methods_supported": [
        "S256"
    ],
    "grant_types_supported": [
        "refresh_token",
        "client_credentials",
        "authorization_code",
        "urn:openid:params:grant-type:ciba"
    ],
    "id_token_encryption_alg_values_supported": [
        "RSA-OAEP-256",
        "RSA-OAEP"
    ],
    "id_token_encryption_enc_values_supported": [
        "A128CBC-HS256",
        "A256GCM"
    ],
    "id_token_signing_alg_values_supported": [
        "PS256",
        "ES256"
    ],
    "introspection_endpoint": "https://as.apiprovider.co.nz/oauth2/introspect",
    "introspection_endpoint_auth_methods_supported": [
        "private_key_jwt"
    ],
    "introspection_endpoint_auth_signing_alg_values_supported": [
        "PS256",
        "ES256"
    ],
    "issuer": "https://as.apiprovider.co.nz/issuer",
    "jwks_uri": "https://as.apiprovider.co.nz/.well-known/jwks",
    "mtls_endpoint_aliases": {
        "token_endpoint": "https://mtls.apiprovider.co.nz/token",
        "revocation_endpoint": "https://mtls.apiprovider.co.nz/revo",
        "introspection_endpoint": "https://mtls.apiprovider.co.nz/introspect"
    },
    "op_policy_uri": "https://as.apiprovider.co.nz/docs/policy",
    "op_tos_uri": "https://as.apiprovider.co.nz/docs/termsofservice",
    "pushed_authorization_request_endpoint": "https://as.apiprovider.co.nz/par",
    "request_object_encryption_alg_values_supported": [
        "RSA-OAEP-256",
        "RSA-OAEP"
    ],
    "request_object_encryption_enc_values_supported": [
        "A128CBC-HS256",
        "A256GCM"
    ],
    "request_object_signing_alg_values_supported": [
        "ES256",
        "PS256"
    ],
    "request_parameter_supported": true,
    "request_uri_parameter_supported": true,
    "require_pushed_authorization_requests": false,
    "require_request_uri_registration": false,
    "require_signed_request_object": true,
    "response_modes_supported": [
        "fragment",
        "jwt"
    ],
    "response_types_supported": [
        "code",
        "code id_token"
    ],
    "revocation_endpoint": "https://as.apiprovider.co.nz/oauth2/revoke",
    "revocation_endpoint_auth_methods_supported": [
        "private_key_jwt"
    ],
    "revocation_endpoint_auth_signing_alg_values_supported": [
        "PS256",
        "ES256"
    ],
    "scopes_supported": [
        "openid",
        "profile",
        "accounts",
        "payments"
    ],
    "service_documentation": "https://as.apiprovider.co.nz/docs",
    "subject_types_supported": [
        "pairwise"
    ],
    "tls_client_certificate_bound_access_tokens": true,
    "token_endpoint": "https://as.apiprovider.co.nz/oauth2/token",
    "token_endpoint_auth_methods_supported": [
        "private_key_jwt"
    ],
    "token_endpoint_auth_signing_alg_values_supported": [
        "ES256",
        "PS256"
    ],
    "ui_locales_supported": [
        "en-nz",
        "mi"
    ],
    "userinfo_encryption_alg_values_supported": [
        "RSA-OAEP-256",
        "RSA-OAEP"
    ],
    "userinfo_encryption_enc_values_supported": [
        "A128CBC-HS256",
        "A256GCM"
    ],
    "userinfo_endpoint": "https://as.apiprovider.co.nz/oauth2/userinfo",
    "userinfo_signing_alg_values_supported": [
        "ES256",
        "PS256"
    ]
}

JSON Schema

The JSON schema for the authorisation server metadata is available in the Security Profile github repository.

Payments NZ API standards

Authorisation Server Metadata v3.0.0