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:

Copy
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:

Copy
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:

OpenID Connect Discovery 1.0

https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata

OpenID Connect Session Management 1.0

https://openid.net/specs/openid-connect-session-1_0.html

OpenID Connect Front-Channel Logout 1.0

https://openid.net/specs/openid-connect-frontchannel-1_0.html

OpenID Connect Back-Channel Logout 1.0

https://openid.net/specs/openid-connect-backchannel-1_0.html

OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens

https://tools.ietf.org/html/draft-ietf-oauth-mtls-08

Standards

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

OpenID Connect & OAuth 2.0

[OIDC-CORE] –http://openid.net/specs/openid-connect-core-1_0.html

[OIDC-BASIC ] – http://openid.net/specs/openid-connect-basic-1_0.html

[OAUTH2] – http://tools.ietf.org/html/rfc6749

[OICD-DISCOVER] – http://openid.net/specs/openid-connect-discovery-1_0.html

[OAUTH2-JWT-GRANT] – https://tools.ietf.org/html/rfc7523

[OIDC-REGISTRATION] - https://openid.net/specs/openid-connect-registration-1_0.html

[OAUTH2-PKCE] - https://tools.ietf.org/html/rfc7636

[OIDC-CIBA-CORE] - https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html

Date Format

ISO8601 formatted JSON String as per Section 7 [RFC7159].

Glossary of Terms

Term Description
ACR

Authentication Context Class Reference

The set of rules required by a provider or relying party that define how a user authenticates to mitigate specific authentication risks using a specific, or combination of, authentication methods.

These rules correspond to the Authenticator Assurance Levels defined in the NIST standard (where 1 is the weakest, and 3 the strongest).

ALSI

Authenticated Login Session Identifier (see Authentication Sessions)

CIBA

Client Initiated Backchannel Authentication

See the OpenID CIBA specification for more details.

Endpoint

An endpoint is a defined base path relative to the ActivID Appliance base URL over which API operations may be performed against protected resources.

JSON

JavaScript Object Notation

Open standard format that uses lightweight text to store and transport data objects consisting of attribute/value pairs. Used primarily to transmit data between a server and web application, as an alternative to XML

See the JSON RFC7159 specification for more details.

JWA

JSON Web Algorithms

See the JWA RFC7518 specification for more details.

JWE

JSON Web Encryption

See the JWE RFC7516 specification for more details.

JWK

JSON Web Key

See the JWK RFC7517 specification for more details.

JWKS

JSON Web Key Set

Signed (RSA or ECDSA algorithms) set of public keys used to verify a JSON Web Key (JWT) issued by an authorization server.

See ActivID Appliance Public Server JWK Set .

JWS

JSON Web Signature

See the JWS RFC7515 specification for more details.

JWT

JSON Web Token

See the JWT RFC7519 specification for more details.

OAuth2

Authorization delegation standard (see Standards for more details).

OIDC

OpenID Connect (see Standards for more details)

OpenID Client

An OpenID client represents a client application of the ActivID Appliance. This allows an application to leverage the ActivID Appliance APIs, and for the authentication server to authenticate the client application. It is setup in ActivID Appliance as a user with valid credentials and permission set.

PALSI

Proxy Authenticated Login Session Identifier (see Authentication Sessions).

PKCE

Proof Key for Code Exchange

See the PKCE RFC7636 specification for more details.

REST

Representational State Transfer

Architectural style used to perform CRUD operations over the web using HTTP methods such as GET, POST, PUT, DELETE

SCIM

System for Cross-domain Identity Management

It is an application-level HTTPS-based protocol with predefined schema for provisioning and managing identity data across domains. The protocol supports creation, modification, retrieval and discovery of core identity resources such as Users and Groups, as well as custom resources and resource extensions.

See the SCIM protocol specifications for more details.

Tenant

In the endpoint, {tenant} is the placeholder for the ActivID Appliance security domain.

Token

A token contains information about the user, their privileges, their group and roles, the authenticator used for the authentication. A token allows you to "prove" that a user is authenticated against ActivID Appliance. A token has a lifetime and thus expires. It is comparable to the principle of web sessions. The token is thus a proof of an identity as well as a credential to access the ActivID Appliance APIs.

ActivID Appliance supports different types of tokens:

  • Access tokens are the most common way to prove an identity, as well as the easiest to use. You can see it as a session identifier. It does not contain any human-readable data. However, you can use it with any of the ActivID Appliance API endpoints to be granted access to it (depending of course on the roles of your user). Access tokens are part of the OAuth2 specification - section 1.4.
  • ID Tokens are always a JWT (JSON Web Token) and comparable to an access token, but holds JSON readable information about the user and the client. It is also signed, which allows you to validate the identity of the owner as well as the Identity Provider (ActivID Appliance). It is a base64URL-encoded JSON formatted piece of data split into three parts - the header, the body and the signature. It is described in the OpenID Core specification.

  • Refresh Tokens can be obtained while getting an access token (in the same request). It is a specific token that allows your application to fetch a new access token (upon expiration of the previous one) without prompting the end user for their credentials. You can thus "refresh" your access token. Refresh tokens are part of the OAuth2 specification - section 6.