What is an OAuth integration?

OAuth is the most common authentication and authorization standard used today. Applications use this standard to rely on external services to identify which user has logged in.

An OAuth integration allows external applications to use the Inbenta login system to authenticate a user. This works exactly the same way as the “Login with Google” button you can find on common web pages, but with Inbenta accounts.

What do I need to configure an OAuth integration?

There are a few requirements to be able to integrate with Inbenta’s login system using the OAuth standard.

• First of all, you need a user group administrator because OAuth applications are related to user groups. User group administrators can manage the OAuth apps that are related to any of the user groups that a given user can manage.
• On the other hand, the screens to manage OAuth applications will be protected by a global right. If you can’t see the section to manage OAuth applications, please contact your administrator.

How do I configure an OAuth application?

You can create new OAuth applications by accessing the Manage OAuth apps tab in the Administration page of your Inbenta App. (This page redirects you to the Inbenta Help Center. You need an Inbenta account to access it.)

Then, follow the steps below to integrate the application.

How to integrate with Inbenta using OAuth?

There are two main steps when integrating an application to an identity provider using the OAuth standard:

1. Get the user authorization
2. Use the user authorization to perform an action

Getting the user authorization

To get the user authorization,  use the OAuth credentials to start the authentication flow with the Inbenta login:

HTTP/1.1 302 Found
Location: https://accounts.inbenta.com/v1/oauth/sign-in?
response_type=code&
client_id=3f44f3b335dfbca8-9fd880312f3eab98&
redirect_uri=https://my-application.com&
state=xx234asdfx0&
scope=personal_information+personal_configuration

This starts the authentication and authorization process of OAuth. The process redirects the user to the Inbenta Login screen:

After the user introduces their credentials, they are prompted to accept or deny the requested scopes by the OAuth application:

After the user accepts the requested scopes, they are redirected back to the specified redirect_uri, with a code query parameter (and the state, if it was provided in the initial request).

HTTP/1.1 302 Found
Location: https://my-application.com?
code=803234affcsa98eeb112&
state=xx234asdfx0

With this code and the Secret Key of the OAuth application, you generate the access token:

POST v1/oauth/tokens HTTP/1.1
Host: accounts.inbenta.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=authorization_code&
code=803234affcsa98eeb112&
redirect_uri=https://my-application.com&
client_id=3f44f3b335dfbca8-9fd880312f3eab98&
client_secret=1bc82afe288104ff011cde1::

If everything is correct, the response contains the access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "2YotnFZFEjr1zCsicMWpAA",
    "token_type": "bearer”,
    "expires_in": 3600
}

The access_token parameter is used to perform actions in the name of the user.

Using the user authorization

Now that you have a valid access token, you can perform any action available with this OAuth access token.

In the following example, you make a request to the Inbenta Accounts service to retrieve the user information:

GET v1/oauth/user-information HTTP/1.1
Host: accounts.inbenta.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

As the access_token was generated for the scopes personal_information and personal_configuration, this endpoint returns all the information available about this user:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "id": "asd98e7ead7fac8sdb7fe123",
    "name": "Michael",
    "email": "michael@test.com",
    "locale": "en",
    "numberSeparators": {
        "thousands": ".",
        "decimal": ","
    },
    "dates": {
        "format": "DD-MM-YYYY",
        "smart": "off"
    },
    "timezone": "Europe/Madrid"
}

For more information about the available resources, see OAuth scopes and resources.