Using Same Sign-on ​

Learn how to use create and use a Same Sign-on Realm.

Introduction ​

We are going to use an example to demonstrate how easy it is to create an SSO Realm and use it with two other realms to allow Same Sign-on.

In this example we will have a user called Linda and three realms com.example.realm.1, com.example.realm.2 and com.example.realm.3.

Linda needs to have access to all realms.Without SSO Realms Linda will have separate credentials per realm.

So the goal of this tutorial is to teach you how to use SSO Realms to allow these users to be able to authenticate in all three realms using a single set of credentials.

1. Creating the SSO realm ​

The first thing we need to do is create the SSO Realm. Let's call it com.example.sso.

The following shows how to create it using the Realm WAMP API to do it.

// Session is attached to Master Realm
// and user has been granted permission
// to call the procedure
session.call("bondy.realm.create", [{
   "uri": "com.example.sso",
   "is_sso_realm": true,
   "allow_connections": false,
   "security_enabled": true,
   "authmethods": []
}])

Notice that in line 3 we set property is_sso_realm to true.

Congratulations, that's all we need to define this realm as an SSO realm!

Also notice that on line 4 we disallow connections. This means no user can open a session attached to this realm (which is the recommended option) as the role of this realm is just to become a shared Identity Provider for other realms.

2. Creating the user realms ​

Now that we have the SSO realm we can put it to work. We now need to create the three realms.

To do that we just need to use the following declaration, replacing the value for uri property with the respective ones defined in the previous section.

// Session is attached to Master Realm
// and user has been granted permission
// to call the procedure
session.call("bondy.realm.create", {
   "uri": "com.example.realm.1", // change for realms 2 and 3
   "is_sso_realm": false,
   "sso_realm_uri": "com.example.sso",
   "allow_connections": true,
   "security_enabled": true,
   "authmethods": ["wampcra", "cryptosign"],
   "sources": [
      ...
   ],
   "groups": [
      ...
   ],
   "grants": [
      ...
   ]
}

Line 7 tells the com.example.realm.1 realm to delegate the management of credentials and authentication to the com.example.sso realm.

Notice that this does not prevent you from having local users (with local credentials) in those realms. By default adding a realm will NOT use the SSO Realm. We need to tell Bondy we want that when creating the users. We will do this in the next step.

3. Adding the user ​

Now that all realms have been created we will add Linda as an "SSO user".

We have two options:

• Direct option: Add the user in the SSO realm first, and then in the other 3 realms.
  1. Create the user in the SSO realm using the bondy.user.add procedure while logged in on the Bondy Admin realm. The call requires passing 2 arguments: the SSO realm URI and a User Data object which should include the user credentials.
  2. Then call bondy.user.add for the com.example.realm.1 realm (without including the credentials).
• Indirect option : Add the user to each realm (only available If the user does not yet exist in the SSO realm):
  1. Create the user in the com.example.realm.1 realm, passing the parameter sso_realm_uri with the URI of the SSO realm supported by the realm , as it will be demonstrated below. Bondy will automatically create the user in the SSO realm.

In the following example we will use Indirect Option to create the user Linda in the three realms realm which will result in the user being also created in the SSO realm and linked to it.

// Session is attached to Master Realm
// and user has been granted permission
// to call the procedure
session.call("bondy.user.add", [
   "com.example.realm.1",
   {
      "username": "linda@gmail.com",
      "password": "123456",
      "groups": ["admin"],
      "meta" : {"country": "us"},
      "sso_realm_uri": "com.example.sso"
   }
])

The above call creates two linked records.

The first record is created in the SSO realm and looks like this:

{
  "username": "linda@gmail.com",
  "password": "123456",
  "groups": ["admin", "owner"],
  "meta" : {"plan": "family +5"}
}

The second record is created in the com.example.realm.1 realm and looks like this:

{
  "username": "linda@gmail.com",
  "sso_realm_uri": "com.example.sso",
  "groups": ["admin"],
  "meta" : {"country": "us"}
}

Notice that the credentials (password in this case) are not in the second record and instead we have a link to the SSO realm which contains the credentials (see the sso_realm_uri property).

We need to repeat the step again to add Linda to realms 2 and 3. Notice that we could remove the password property now as it will be ignored since Linda already exists in the SSO Realm.

The following diagram shows the end result:

Now Linda can authenticate to all three realms using a single set of credentuals. Moreover, performing a password change on any of the three realms will actually change it in the SSO realm, having immediate effect across all associated realms.

FAQs ​

Is this the same as Single Sign-on? ​

No. Same Sign-on still requires the user to authenticate again when opening a session on a realm. See Bondy Single Sign-on.

Where does the authorization happen? ​

Authorization is still performed by the realm the user is connecting to. That means the permissions will be those granted by the local RBAC configuration for the realm. Bondy Same Sign-on only handles authentication.

Do I need to change the clients code to use Same Sign-on? ​

There is no need to change the client code to use Same Sign-on. The user can login using its credentials to any of the realms it belongs to.

Which realm should I use for changing an SSO user credentials? ​

Changing credentials (password or authorized_keys) can be done by calling the Bondy APIs while logged-in on any of the realms the user is associated with, Bondy will forward the operation to the linked SSO realm.

Can I create local (non SSO) users on my realm? ​

Yes. Users can still be created just on your realm (aka a "Local" user). T

To do this we just create the user without specifying a value for the property sso_realm_uri or setting it to null.