Authentication

Authentication Providers

Get available auth providers

GET /providers/auth/available

List all available Authentication providers

Response JSON Array of Objects:

  • name (string) – Provider name

  • icon (string) – A URL pointing to a suitable icon for the provider

Get user authentication method

GET /users/(string: userId)/auth

Allows to get the authentication method for a user. Returns a detailed object with the authentication method for the user (i.e. OAuth, Custom etc)

Parameters:

  • userId (string)

Query Parameters:

  • for_client (string)

Response JSON Object:

  • provider (provider) – Identity provider of a given user.

List authentication providers

GET /clients/(string: clientId)/providers/auth

Retrieve the list of authentication OAuth providers configured for given client. Those providers can be only used for user authentication. This method is publicly available as it does not require a token in the header. Your choice of Oauth providers is thus public. The response contains a URL containing the logo for the providers and can be downloaded as a convenience to the developer.

Parameters:

  • clientId (string) – Specifies the client for which supported OAuth providers are required

Response JSON Object:

  • providers (seq[providerbaseinfo]) – List of providers with a description

  • defaultProvider (option[string]) – Provider that was chosen as default provider

Set authentication providers

POST /providers/auth

Set list of possible authentication provider in all channels that belongs to client. Request should be an list of provider names to set.

Request: List of Strings

Get details from provider

GET /auth/profile

Function to retrieve any profile information available about this user from their auth provider. This includes information such as their names, email address, image etc. Effectively, this is whatever information Horn was able to retrieve from the user for this profile.

Response JSON Object:

  • name (string) – Name of a provider.

  • email (string) – Email address of a provider.

  • imageUrl (string) – URL to the provider’s image.

Terms and Conditions

Accept the current terms and conditions

POST /users/me/terms/(number: version)

Users are required to accept the current terms and conditions. As these will change from time to time, the user is required to accept the latest version of these terms. See the GET verb for obtaining the current terms and conditions state for the user. The “version” parameter must be the version returned by the GET verb for this path. Note that authentication to the system is denied if the user has not accepted the current terms.

Parameters:

  • version (number) – The version of the terms that this user is accepting.

Get the terms and conditions

GET /clients/(string: clientId)/terms

Returns current T&C URL. This call does not require authentication.

Parameters:

  • clientId (string) – Specifies the client whose terms will be returned

Response JSON Object:

  • version (int) – The current version if the user needs to sign an updated version

  • url (string) – A URL pointing to the latest terms and conditions

  • promulgated (long) – Promulgated date

  • required (boolean) – Are Terms acceptance an required step? If false, it means Guests can skip accepting terms step

Get the terms and conditions state

GET /users/me/terms

Get the state of the user’s terms and conditions acceptance. If the user has not accepted the latest terms and conditions then the “isCurrent” field will be “false” and the user should be directed to the terms and conditions page (the “termsUrl” field contains a link to the current version). Finally, the “currentVersion” field is the version that the user is required to accept. If the firstAccept field is set to true then this user has never accepted our terms previously.

Response JSON Object:

  • isCurrent (boolean) – True idf the user has signed the current terms and conditions

  • currentVersion (int) – The current version if the user needs to sign an updated version

  • termsUrl (string) – A URL pointing to the latest terms and conditions

  • firstAccept (boolean) – : True if this is the user’s first T&C acceptance

Set terms and conditions

POST /terms

Update the T&Cs link for the current client. This will not require users to explicitly accept the new T&Cs. The caller is responsible for making sure that users are notified of this change in an appropriate manner.

Request JSON Object:

  • url (string) – A URL pointing to the latest terms and conditions

Set terms and conditions - require re-acceptance

POST /terms/new

Set a new T&Cs link for the current client. This will cause all users to be prompted to accept the new T&Cs. Users will not be able to log in or use the system until they have accepted the new terms.

Request JSON Object:

  • url (string) – A URL pointing to the latest terms and conditions

Custom Authentication

By default, Horn supports authenticating users via OAuth against one of a number of common public endpoints. Custom OAuth endpoints can also be added and used (see Horn for details).

In situations where OAuth is not a viable option, or where it is important that the end-user _never_ be prompted to login, Horn also supports authentication via JWT (see https://jwt.io). Before JWT authentication can be used, at least one “custom auth validator” needs to be set up. Initial setup of a custom auth validator is not possible through the API - contact Horn to get your validators established.

This section describes the API calls that can be used to manage custom authentication validators used for JWT-based authentication.

Disable validator

POST /validators/(string: validatorId)/disable

Disable a custom validator, preventing it from being used for custom authentication.

Parameters:

  • validatorId (string) – Validator Identifier

Query Parameters:

  • for_client (string) – If specified, executes call in the context of the identified clientId, which must be a child account of calling user”s” client. (Partner Admins only)

Enable validator

POST /validators/(string: validatorId)/enable

Set one of the available custom authenticators to be active. Possible options can be enumerated with the List Validator call. Note: Only one validator can be active at any given time. Enabling a validator will automatically disable any previously active validator.

Parameters:

  • validatorId (string) – ID of the validator to enable.

Query Parameters:

  • for_client (string) – If specified, executes call in the context of the identified clientId, which must be a child account of calling user”s” client. (Partner Admins only)

List validators

GET /validators

List all possible custom authentication validators that could be assigned to the given client. Note that while multiple validators can exist, only one can be assigned (i.e. active) at a given time.

Query Parameters:

  • for_client (string) – If specified, executes call in the context of the identified clientId, which must be a child account of calling user”s” client. (Partner Admins only)

Exchange OpenID token

POST /clients/(string: clientId)/users/exchange

Exchanges Open ID Token to Horn token to allow user use Horn ecosystem. This method updates some details about user if found in id token payload. I.e. name or picture can be updated in Horn database after successful token validation.

Parameters:

  • clientId (string) – Specifies the client against which to validate id token and authorize user

Request JSON Object:

  • idToken (string)

Response JSON Object:

  • token (string) – The user’s secret token

  • expires (long) – The ttl of token