About the HID Authentication Service OpenID API

The HID Authentication Service OpenID Connect API is used by client applications to verify the identity of users (that is, perform user authentication). The HID Authentication Service supports a range of authentication mechanisms from memorized secrets to multi-factor authentication. The choice of authenticator depends on business risk and user convenience.

The API allows you to retrieve bearer tokens that allow you to fully delegate the authentication from your application to the HID Authentication Service, whether it is a mobile, a web-based or a desktop application. This enables a modern type of authentication, where end-user credentials and secrets are not shared with potentially insecure relying-party applications.

The HID Authentication Service OpenID Connect API exposes the authentication and authorization RESTful endpoints added to the HID Authentication Service server that conform to standard OAuth 2.0 and OpenID Connect protocols.

The following sections provide details of the API to help the integrator to use the Identity Provider (IdP) with OAuth 2.0 client applications to access RESTful API endpoints.

It covers the architecture, software requirements, technology stack, resource endpoints, message formats, error codes and other technical specifications.

OpenID Connect follows the below sequence of operations to authorize an end user and return information about that end user:

1. The client application directs the user to the HID Authentication Service.

2. The HID Authentication Service authenticates the end user and generates an authorization code.

3. The client application receives the authorization code and uses it to request tokens from the HID Authentication Service.

4. The HID Authentication Service responds with an ID Token and usually an Access Token.

5. The client application can send a request with the received Access Token to the UserInfo endpoint.

6. The UserInfo endpoint returns claims about the end user.

For a more detailed overview of OAuth 2.0 and OpenID Connect, see Support of OAuth 2.0/OpenID Connect Specifications.

The API reference content is designed to help developers understand:

• Resource endpoints
• CRUD (HTTPS methods) operation on resources
• Request and Response payloads
• Content-type application/json; charset=UTF-8 and application/x-www-form-urlencoded
• Error codes

Base URI

• All URLs referenced in this API documentation begin with the following base URL:

https://[base-server-url]/{tenant}

• All references to [base-server-url] are a placeholder to be replaced with <your-service-platform>/idp (see HID Authentication Service Platforms)

• All references to {tenant} are a placeholder to be replaced with your tenant ID

Discovering the Server’s Endpoints and Capabilities

The HID Authentication Service server publishes its OIDC provider metadata in JSON format (as specified in OpenID Connect Discovery – section 3) at the following URL:

https://[base-server-url]/{tenant}/authn/.well-known/openid-configuration [GET]

In response, the server returns a JSON object listing the standard OpenID endpoints and parameters:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "issuer": "https://[server-host]/idp/{tenant}/authn",
    "jwks_uri": "https://[server-host]/idp/{tenant}/authn/jwks",
    "authorization_endpoint": "https://[server-host]/idp/{tenant}/authn/login",
    "token_endpoint": "https://[server-host]/idp/{tenant}/authn/token",
    "registration_endpoint": "https://[server-host]/idp/{tenant}/authn/register",
    "introspection_endpoint": "https://[server-host]/idp/{tenant}/authn/introspect",
    "scopes_supported": [
        "openid",
        "profile",
        "offline_access"
    ],
    "response_types_supported": [
        "code",
        "code id_token",
        "id_token"
    ],
    "response_modes_supported": [
        "query",
        "fragment",
        "form_post"
    ],
    "grant_types_supported": [
        "authorization_code",
        "client_credentials",
        "password",
        "urn:ietf:params:oauth:grant-type:jwt-bearer",
        "urn:hid:oauth:grant-type:client-secret-pki",
        "refresh_token",
        "urn:openid:params:grant-type:ciba",
        "ciba_delete",
        "api_otp",
        "implicit"
    ],
    "token_endpoint_auth_methods_supported": [
        "client_secret_basic",
        "client_secret_post",
        "private_key_jwt",
        "client_secret_pki",
        "tls_client_auth",
        "self_signed_tls_client_auth"
    ],
    "ui_locales_supported": [
        "en"
    ],
    "request_parameter_supported": true,
    "request_uri_parameter_supported": true,
    "require_request_uri_registration": false,
    "tls_client_certificate_bound_access_tokens": false,
    "backchannel_token_delivery_modes_supported": [
        "push",
        "poll"
    ],
    "pushed_authorization_request_endpoint": "https://[server-host]/idp/{tenant}/authn/par",
    "backchannel_authentication_endpoint": "https://[server-host]/idp/{tenant}/authn/bcauthorize",
    "subject_types_supported": [
        "public"
    ],
    "userinfo_endpoint": "https://[server-host]/idp/{tenant}/authn/userinfo",
    "end_session_endpoint": "https://[server-host]/idp/{tenant}/authn/logout",
    "revocation_endpoint": "https://[server-host]/idp/{tenant}/authn/revoke",
    "acr_values_supported": [
        "1",
        "2",
        "3",
        "4"
    ],
    "id_token_signing_alg_values_supported": [
        "RS256",
        "none"
    ],
    "id_token_encryption_alg_values_supported": [
        "RSA-OAEP-256"
    ],
    "userinfo_signing_alg_values_supported": [
        "RS256",
        "none"
    ],
    "userinfo_encryption_alg_values_supported": [
        "RSA-OAEP-256"
    ],
    "display_values_supported": [
        "page",
        "popup"
    ],
    "claim_types_supported": [
        "normal"
    ],
    "claims_supported": [
        "sub",
        "iss",
        "aud",
        "exp",
        "iat",
        "auth_time",
        "acr",
        "amr",
        "nonce",
        "preferred_username",
        "groupids",
        "role",
        "securitygroupids",
        "name",
        "at_hash",
        "c_hash",
        "sid",
        "email"
    ],
    "claims_parameter_supported": true,
    "frontchannel_logout_supported": false,
    "backchannel_logout_supported": false
}

For the full list of available endpoints (standard and HID-specific), see HID Authentication Service OpenID API Endpoints.

OpenID Provider Metadata

The OpenID provider metadata parameters supported are documented in the following documents:

Standards

The API uses a standards-based approach to facilitate client integration. The supported standards are:

Glossary of Terms