In the previous blog, you could read how to set up the connection with Azure Active Directory (AAD) and the Content Hub. In the episode, we are going to take a look at how to organize the user rights between these two.
After setting up the connection between the Content Hub and Azure Active Directory, the users can log in to the Content Hub, but they can't actually do anything yet. This has to do with the fact that the users don't have any rights within the Content Hub yet. So let's take a look at how we can achieve that.
After a user has signed in, into the Content Hub, an account will be created for that user. You can see those accounts when you go to the Manage -> Users page. There you'll find an overview of all the users, including the users that have signed in through AAD. When you open such a user account, you can assign rights to them like any other account. This works fine when you only have a couple of users. When the number of users increases above 50, the manual process will become tedious. So what can we do to automate this process?
Well, that's is quite easy. The AAD already supplies us with some necessary information about the user his rights. The AAD gives us access to the claims that we configured in the previous blog post. With each claim the AAD gives us, we can use it to translate into user rights within the Content Hub. Saving us a lot of manual work.
Before we start configuring the translation of the claims into rights. Lets first start with what a claim actually is. Simply put, claims are name/value pairs that contain information about a user, as well meta-information about the OIDC service. The official definition from the spec is a “piece of information asserted about an Entity.” (copied from: Okta). Here below, you can find how claims actually looks in JSON.
{
"family_name": "Silverman",
"given_name": "Micah",
"locale": "en-US",
"name": "Micah Silverman",
"preferred_username": "micah.silverman@okta.com",
"sub": "00u9vme99nxudvxZA0h7",
"updated_at": 1490198843,
"zoneinfo": "America/Los_Angeles"
}As you can see this piece of JSON contains multiple claims: family_name, given_name, locale, etc. The more claims you add from AAD, the more information that you have to better configure the user his rights within the Content Hub. Now that we understand what a claim is, we can start translating the claims into user rights.
To do this, we need to use a script type within the Content Hub. Let us first take a look at the documentation about the scripts. You can see that the Content Hub supports different scripts. For our purpose, we need the user post-registration script. The user post-registration scripts are executed every time a new user is created.
Warning: the Content Hub also offers a login script, but this script is rather dangerous to be used. As stated by the documentation, when a script fails it can cause a user not to be able to log on.
WARNING
- The User sign-in script might lock users out when there are inconsistent user validations in the script or any other runtime errors. This includes superusers and administrators.
- This lock-out can be resolved by de-activating the script using the REST API or SDK.
Now that we've chosen the script type, we can start creating our code to read the claims and translate these to our Content Hub user rights. Since each implementation is different, there aren't many claims that are the same. See the Azure Active Directory configuration to know which claims are available for you to read.
Go to the Manage portal in the Content Hub and then to Scripts. Click on + Script to create a new script. When the pop-up opens, name the script and select "User post-registration" for the script type. For easier maintenance, also add a description to the script. Make sure to always validate the description when updating the script. This way, you make sure that the script does what the description says. Now that we have a placeholder for the script, we can start scripting. For basic information check this page in the documentation. It briefly explains how this script could be used.
The easiest way to get started is to read and log all the claims that are available for you to use. But how can we actually read the claims? Well, as with all scripts in the Content Hub, we can use the Context. This is an object from the Content Hub that we can leverage to interact with the system. It's within this object we can also find the claims that we need. With the following line of code, we get access to the claims.
Context.ExternalUserInfo.Claims
The ExternaluserInfo class contains multiple properties that we can use. But the one that we are interested in is the Claims property. This is a read-only list with claims. Each claim has two properties, a Type and a Value. The type of claim can also be seen as a key. By reading this type, you know the meaning of the claim. For instance; the Type property has the following value: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name". This means that the claim Value contains the name of the person that is trying to log on. Another claim that we see very often is the "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" type. This claim contains the email address of the person.
The easiest way to get all claims is just to iterate over the Claims property in the ExternaluserInfo class and log them.
foreach(var claim in Context.ExternalUserInfo.Claims
{
MClient.Logger.Info($"Claim type: {claim.Type} ## {claim.Value}");
}
This will code snippet will give you all the information you need to start connecting a person to the right user groups. Keep in mind, that this script ONLY runs once when a user is created. So after you log in for the first time, your account has been created and this script will not be fired again! For debugging purpose, you could also you the User sign-in script, but make sure to always add a try/catch around the code. Otherwise, you could be locking yourself out of the Content Hub.