Creating and using Realms in the Platform

onesait Platform is preapred to work as an OAuth2 Server for external applications.

In this example, we will configure a realm in the Open Platform and we will authenticate against it through REST services.

Realm Configuration

Firstly, access the platform with the developer role, and access My Realms section in the Development menu.

In this screen, click thebutton and fill the form with Application details: realm's unique identifier, name and a description. Secret and Token validity seconds are non required attributes associated with Oauth2 Authentication.

Once the general data are completed, you can start defining the roles within the Realm. You can define as many roles as needed.

All changes will be stored when you click on . A new Realm will be created (and the creator user will be its owner).

Adding Users to the Realms and assigning Roles

Once the Realm is created, the owner user (or any user with developer role) can register users to the realm.

To do so, you have to edit the Realm, by clicking on the edit button on the corresponding line of the Realm list.

Then, access the tab to register users:

In this section, you can register users, assigning them a role in the realm. A single user can register with several Roles in the Realm.

Select the user and the Role in the Realm, and click

Once an user has been registered, it can be deleted by clicking on the button.

To store the changes, select the tab and click on

Mapping registered Users in a LDAP.

If LDAP authentication is used in your deployed platform, you will see a checkbox in the User Assignment tab. You can search and import LDAP users, as well as existing LDAP groups.

By checking this box, you can search by DN users and groups.

If you want to import LDAP users, fill the underneath 'USERS DN BASE' with the DN. This operation will search all users belonging to that DN.

The same can be done for groups.

When an LDAP group is mapped to a ROLE, all users will be created on the platform associated with that role.

Realm Associations

To establish a hierarchy of Realms, you can define associations between Realms.

When establishing an association between realms, you must create a mapping between the Realm roles and the associated Realm roles. Thus, when a user authenticates against a Realm, she will get the roles of the Realm and the roles of the associated role that are mapped.

To establish an association, first select a Role from the Realm, then select the Realm to be associated. Once the Realm is selected, you will see a combo with all the Realms that can be associated.

To end the association, select a Role and click

The association will be added to the list. Multiple association between Roles can be defined. To remove an association, click button

When all the changes are made, return to the first tab and click thebutton to save the changes.

OAuth2 Authentication

To authenticate the user, using the created Realm, you must make call to a POST REST service to https://www.onesaitplatform.online/controlpanel/oauth-server/oauth/token

This REST request must include authentication parameters using Basic Auth with the Realm id and the default username and password (onesaitplatform) (It can be configured in the Realm definition, see above).

Using Postman, the request should look like this:

In the body of the request, you must enter the authentication parameters:

grant_type: password
username: the name of the user to authenticate.
password: the password of the user to authenticate.
clientId: realm's id.
scope: openid

When sending this, you should receive as a response a JSON with all the relevant information about the login, including the user (as name or principal), access_token, Realm Id (as clientId), list of roles of the logged user (as authorities) and a list of associated realms (apps) and the roles that the user has in each of them.

The following is an example of a token response:

This is the same example using curl:

curl example

curl \
--user "ExampleRealm:onesaitplatform" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password&username=developer&password=your_password&clientId=ExampleRealm&scope=openid" \
-X POST https://www.onesaitplatform.online/controlpanel/oauth-server/oauth/token \
--insecure

You can validate a token against the server by sending a GETrequest to the endpoint https://www.onesaitplatform.online/controlpanel/oauth-server/openplatform-oauth/check_token with the token as basic authentication parameter:

The response should be a JSON with the basic information of the token:

This is the same example with curl:

Example with Curl

curl \
--user "ExampleRealm:onesaitplatform" \
-d "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcmluY2lwYWwiOiJkYXRhaGlzdG9yaWFuIiwiY2xpZW50SWQiOiJkYXRhaGlzdG9yaWFuIiwidXNlcl9uYW1lIjoiZGF0YWhpc3RvcmlhbiIsInNjb3BlIjpbIm9wZW5pZCJdLCJuYW1lIjoiZGF0YWhpc3RvcmlhbiIsImV4cCI6MTU0MzM1NzkzOSwiZ3JhbnRUeXBlIjoicGFzc3dvcmQiLCJwYXJhbWV0ZXJzIjp7ImNsaWVudElkIjoiZGF0YWhpc3RvcmlhbiIsImdyYW50X3R5cGUiOiJwYXNzd29yZCIsInVzZXJuYW1lIjoiZGF0YWhpc3RvcmlhbiIsInNjb3BlIjoib3BlbmlkIn0sImF1dGhvcml0aWVzIjpbImFkbWluIl0sImp0aSI6Ijc5ZGQzNTI3LTFhNDMtNDQ5NS1hN2EwLWI1NTcyZjQ0MDYzZSIsImNsaWVudF9pZCI6ImRhdGFoaXN0b3JpYW4iLCJhcHBzIjp7fX0.7v5Owv_soQk5wkCE1NOJED6Soncpylo7K5KurNjg1M0"  \ 
-X GET https://www.onesaitplatform.online/controlpanel/oauth-server/openplatform-oauth/check_token \
--insecure