Getting Started with the ActivID Appliance OpenID API

The ActivID Appliance OpenID Connect API is used by client applications to verify the identity of users (that is, perform user authentication). The ActivID Appliance 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 ActivID Appliance, 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 ActivID Appliance OpenID Connect API exposes the authentication and authorization RESTful endpoints added to the ActivID Appliance 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 ActivID Appliance.

2. The ActivID Appliance 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 ActivID Appliance.

4. The ActivID Appliance 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 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-server-host>:<port>/idp

• All references to {tenant} are a placeholder to be replaced with the target security domain name

Discovering the Server’s Endpoints and Capabilities

The ActivID Appliance 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://[base-server-url]/{tenant}/authn",
    "token_endpoint": "https://[base-server-url]/{tenant}/authn/token",
    "authorization_endpoint": "https://[base-server-url]/{tenant}/authn/login",
    "userinfo_endpoint": "https://[base-server-url]/{tenant}/authn/userinfo",
    "registration_endpoint": "https://[base-server-url]/{tenant}/authn/register",
    "introspection_endpoint": "https://[base-server-url]/{tenant}/authn/introspect",
    "bcauthorize_endpoint": "https://[base-server-url]/{tenant}/authn/bcauthorize ",
    "jwks_uri": "https://[base-server-url]/{tenant}/authn/jwks",
    "end_session_endpoint": "https://[base-server-url]/{tenant}/authn/revoke",
    "scopes_supported": ["openid","profile","offline_access"],
    "response_types_supported": ["code"],
    "response_modes_supported": ["query","fragment"],
    "grant_types_supported": [
        "password",
        "authorization_code",
        "client_credentials",
        "refresh_token",
        "urn:hid:oauth:grant-type:client-secret-pki",
        "urn:ietf:params:oauth:grant-type:jwt-bearer"],
    "subject_types_supported": ["public"],
    "token_endpoint_auth_methods_supported": [
        "client_secret_post",
        "client_secret_basic",
        "client_secret_pki",
        "private_key_jwt",
        "self_signed_tls_client_auth"],
    "acr_values_supported": ["1","2","3","4"],
    "id_token_signing_alg_values_supported": [“RS256"],
    "id_token_encryption_alg_values_supported": ["RSA-OAEP-256"],
    "userinfo_signing_alg_values_supported": ["none”,"RS256"],
    "userinfo_encryption_alg_values_supported": ["RSA-OAEP-256"],
    "display_values_supported": ["page","popup"],
    "claim_types_supported": ["normal"],
    "claims_supported": ["sub","iss","aud","exp","iat","acr","preferred_username","groupids","role","email"],
    "ui_locales_supported": ["en"],
    "claims_parameter_supported": true,
    "request_parameter_supported": true,
    "request_uri_parameter_supported": false,
    "require_request_uri_registration": false,
    "frontchannel_logout_supported": false,
    "backchannel_logout_supported": false,
}

For the full list of available endpoints (standard and HID-specific), see ActivID Appliance 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