Identity management and federation

Developers – Identity

Most Speakup APIs use OAuth2/OpenID Connect to authorize the calls that you make to our services. When you register the application or service that you are developing, you will be issued a set of credentials that can be used to authenticate users and/or authorize API access: a “Client ID” and a “Client Secret”. As the name implies: you should keep the latter private.

APIs at Speakup come in two flavors:

  • There are APIs that act on behalf of a user (an example would be an API to control the user’s queue membership on the PBX or read presence information of colleagues). These APIs use the OpenID Connect protocol to obtain access tokens that are issued on behalf of a user. These may use the OpenID Connect “Authorization code” grant type.
  • APIs that are not speficically tied to a user (such as sending an SMS) use the OAuth2 “Client Credentials” grant. You can think of such API-calls as being scoped to an organization or team instead of to an individual user.

Obtaining an access token using OpenID Connect

When accessing an API that acts on behalf of a user, the user needs to be authenticated. This is accomplished by redirecting the user to the Speakup Identity Server where authentication is performed. This process also gives the user the chance to give consent to any access the application requests. By using this approach, the credentials of the user will remain shielded from the application at all times.

The recommended way to obtain an access token using OpenID Connect from within a web application is using the “Authorization code” flow if the application has a backend service that can perform the required backchannel communication.

If on the other hand the client doesn’t use a backend service, the “Implicit” flow can also be used.

Please refer to this OAuth2 documentation on how to perform the user authentication from within your application: https://oauth.net/2/grant-types/

Obtaining an access token using client credentials

If a Speakup user is not directly involved in the API call, access tokens are retrieved directly by invoking the OAuth2 token endpoint (https://oauth.net/2/grant-types/client-credentials/). To obtain an access token perform the following HTTP call:

POST https://account.speakup.nl/auth/realms/public/protocol/openid-connect/token

Include the following form parameters in your call (application/x-www-form-urlencoded):

  • grant_type: Must be “client_credentials”
  • scope: A space separated list of scopes that give you access to APIs. Each Speakup API has one or more scopes that you can request.
  • client_id: The Client ID issued by Speakup.
  • client_secret: The Client Secret issued by Speakup.

When succesful, the server will respond with a JSON body containing the keys “access_token” and “refresh_token”. Note that access tokens can be reused until they expire. Once expired, you can create a new access token either by re-authenticating or by using the refresh token in the OAuth2 “Refresh Token” flow (https://oauth.net/2/grant-types/refresh-token/).

Identity server endpoints

The Speakup identity server uses the following endpoints:

  • OpenID Connect metadata, containing all endpoint URIs and capabilities: https://account.speakup.nl/auth/realms/public/.well-known/openid-configuration
  • The authorization endpoint, used to perform authentication and authorization for a user: https://account.speakup.nl/auth/realms/public/protocol/openid-connect/auth
  • The token endpoint, used to retrieve an access token: https://account.speakup.nl/auth/realms/public/protocol/openid-connect/token