SSO: Advanced identity setups

babelforce offers the option for advanced SSO setups.

This article is only relevant for IAM systems that use any unique identifier that is NOT email. Please only continue if this applies to your case. For email as unique identifier, no additional API calls to babelforce backend are necessary and setup via the manager app is possible. For the simple email case, view this article.

babelforce SSO setup is very flexible. We allow you to identify and login your users to babelforce by requesting any scope and claim(s) that your IAM system is providing.

Below, we explain which APIs you have to use and how to configure SSO in the babelforce Manager app.

How it works

When configuring SSO in babelforce, the default "Principal Claim" is email. This means by default babelforce is expecting that email is used as unique identifier in your IAM system.

The "Principal Claim" you enter in babelforce represents an openid connect scope and a list of claims babelforce uses to identify a user. In the example above, the openid connect scope and the claim is email. In this case, the scope and claim are the same. 

But the cases we want look at are more complex. For instance, you have an openid connect scope called profile and there is a single claim that belongs to each user's profile, let's say it's called preferred_username. So in this case, you want to identify your users with a scope called "profile" and the claim "preferred_username"

User Mr. X

profile
 preferred_username: mrx

In this case, you use a simple notation to tell babelforce your scope and your claim:

profile=>[preferred_username]

And that's how this specific setting would look like in babelforce:

There can be multiple claims added each with different claims. This for instance is possible:

profile=>[id];email;upn=>[name,active]

Your IAM system would provide three scropes, each with different claims that are linked to a user

User Mrs. X

profile
 id: 3423k4afs

email
 email: mrs.x@example.com

upn
 name: Mrs. X
 active: true

Next, you need to let babelforce know which scopes and claims belong to which user. You link this data with the matching babelforce user id in the babelforce backend (this implies that you need to first create a babelforce user, retrieve the user's id and then use it in the api call to configure the babelforce SSO system).

To configure a user's scopes and claims, use this endpoint: 

POST: ​/auth​/sso​/configuration​/{user}​/identities

(To see the full openapi spec, get in touch with support@babelforce.com)

In the request body babelforce expects this:

{
  "claims": [
  {
    "name": "{{claim1}}",
    "values": {
      "{{property1}}": "{{value1}}",
      "{{property2}}": "{{value2}}"
    }
  }
  {
    "name": "{{claim2}}",
    "values": {
      "{{property3}}": "{{value3}}"
      }
    }
    ]
  }

To make this easier, let's look at the body you should post for the user Mr. X we defined above that has the following properties in your IAM system:

User Mr. X

profile
 preferred_username: mrx

And that's what babelforce expects in the API body:

{
  "claims": [
  {
    "name": "profile",
    "values": {
      "preferred_username": "mrx"
    }
  }
}

To wrap up, let's look at the API call we would expect for our other example. Mrs. X.

These were Mrs. X properties in your IAM system:

User Mrs. X

profile
 id: 3423k4afs

email
 email: mrs.x@example.com

upn
 name: Mrs. X
 active: true

And that's what you sent to babelforce:

{
  "claims": [
  {
   "name": "profile",
   "values": {
      "id": "3423k4afs"
    }
  }
  {
    "name": "email",
    "values": {
      "email": "mrs.x@example.com
    }
  }
 {
    "name": "upn",
    "values": {
      "name": "Mrs. X",
      "active": "true"
  }
}