Using the Well-Known UMA Endpoint

AM exposes an endpoint for discovering information about the UMA provider configuration.

When making a REST API call, specify the realm in the path component of the endpoint. You must specify the entire hierarchy of the realm, starting at the Top Level Realm. Prefix each realm in the hierarchy with the realms/ keyword. For example /realms/root/realms/customers/realms/europe.

A resource server or client can perform an HTTP GET on /uma/.well-known/uma2-configuration to retrieve a JSON object indicating the UMA configuration.

To use the endpoint, you must first create both an OAuth 2.0 Provider service, and an UMA Provider service in AM. For more information on creating these services, see Authorization Server Configuration and "To Create the UMA Provider Service".

Tip

Resource servers and clients need to be able to discover the UMA provider for a resource owner. You should consider redirecting requests to URIs at the server root, such as https://www.example.com/.well-known/uma2-configuration, to the well-known URIs in AM's space.

For example, if your UMA provider is in a subrealm named subrealm, you could map the following URI: https://www.example.com:8080/openam/uma/realms/root/realms/subrealm/.well-known/uma2-configuration.

Note

AM supports a provider service that allows a realm to have a configured option for obtaining the base URL (including protocol) for components that need to return a URL to the client. This service is used to provide the URL base that is used in the .well-known endpoints used in OpenID Connect 1.0 and UMA.

For more information, see "Configuring the Base URL Source Service".

The following is an example of a GET request to the UMA 2.0 configuration discovery endpoint for a subrealm named subrealm in the Top Level Realm:

$ curl \
--request GET \
https://openam.example.com:8443/openam/uma/realms/root/realms/subrealm/.well-known/uma2-configuration
{
    "issuer": "https://openam.example.com:8443/openam/oauth2/subrealm",
    "grant_types_supported": [
        "urn:ietf:params:oauth:grant-type:saml2-bearer",
        "urn:ietf:params:oauth:grant-type:uma-ticket",
        "client_credentials",
        "password",
        "authorization_code",
        "urn:ietf:params:oauth:grant-type:device_code",
        "http://oauth.net/grant_type/device/1.0"
    ],
    "token_endpoint_auth_methods_supported": [
        "client_secret_post",
        "private_key_jwt",
        "client_secret_basic"
    ],
    "revocation_endpoint_auth_methods_supported": [
        "client_secret_post",
        "private_key_jwt",
        "client_secret_basic"
    ],
    "response_types_supported": [
        "code token id_token",
        "code",
        "code id_token",
        "device_code",
        "id_token",
        "code token",
        "token",
        "token id_token"
    ],
    "jwks_uri": "https://openam.example.com:8443/openam/oauth2/realms/root/realms/subrealm/connect/jwk_uri",
    "dynamic_client_endpoint": "https://openam.example.com:8443/openam/oauth2/realms/root/realms/subrealm/register",
    "token_endpoint": "https://openam.example.com:8443/openam/oauth2/realms/root/realms/subrealm/access_token",
    "authorization_endpoint": "https://openam.example.com:8443/openam/oauth2/realms/root/realms/subrealm/authorize",
    "revocation_endpoint": "https://openam.example.com:8443/openam/oauth2/realms/root/realms/subrealm/token/revoke",
    "introspection_endpoint": "https://openam.example.com:8443/openam/oauth2/realms/root/realms/subrealm/introspect",
    "resource_registration_endpoint": "https://openam.example.com:8443/openam/uma/realms/root/realms/subrealm/resource_set",
    "permission_endpoint": "https://openam.example.com:8443/openam/uma/realms/root/realms/subrealm/permission_request"
}

The JSON object returned includes the following configuration information:

issuer

The URI of the issuing authorization server.

grant_types_supported

The supported OAuth 2.0 grant types.

token_endpoint

The URI to request tokens.

authorization_endpoint

The URI to request authorization for issuing a token.

introspection_endpoint

The URI to introspect an RPT.

For more information, see "/oauth2/introspect".

resource_registration_endpoint

The URI for a resource server to register a resource.

For more information, see Managing UMA Resources.

dynamic_client_endpoint

The URI for registering a dynamic client.