Adding claims from authentication

Authentication Attributes into claims¶

The Curity Authentication Service has very large support for collecting user attributes during authentication using authentication actions to lookup attributes in external repositories, dynamically prompting for additional authentication methods, adding geo data, etc. These collected attributes are not automatically added to tokens issued by the Curity Token Service, instead each attribute has to be configured to be issued. This article will shed some light on how this is done.

The Claims Provider¶

In this article the focus will be on the Authentication Subject claims provider. This type is not added by default, and will have to be added before the claims definitions can be added. To add this, go to

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

<config xmlns="http://tail-f.com/ns/config/1.0">
  <profiles xmlns="https://curity.se/ns/conf/base">
  <profile>
    <id>oauth-dev</id>
    <type xmlns:as="https://curity.se/ns/conf/profile/oauth">as:oauth-service</type>
      <settings>
      <authorization-server xmlns="https://curity.se/ns/conf/profile/oauth">
      <claims>
      <claims-value-provider>
        <id>authn-subject</id>
        <authentication-subject-claims-provider xmlns="https://curity.se/ns/ext-conf/authentication-subject-claims-provider"/>
      </claims-value-provider>
      </claims>
      </authorization-server>
      </settings>
  </profile>
  </profiles>
</config>

Adding a claim¶

The default tokens does not contain any user related data, other than the sub and contextual information like acr. Additional claims that are supposed to go in to the token(s) are configured in the Claims subsection of the Token Profile. The preconditions for a claim ending up in a token can be read about in Claims Explained.

A claim has three columns of configuration concerning the value: Claims Source, Atttributes and Transformation. Consider this screenshot of an email claim:

This configuration chooses the Authenticated Subject as the source of the value. In the subject there is an attribute email, the value of which will be added to the email claim without any transformation. In addition, the claim is configured to be included in both id_token and userinfo when a client is granted the scope openid or email. In the end, this means that a client requesting the scope openid will get an ID Token containing the email claim, if an attribute called email can be be found in the output of the authentication. It might be easy to know exactly what attributes are in the authenticated subject, but many times you will have to search the log files to find out exactly how the responses look like. To help with that type of debugging, there is the Debug Authentication Action

Debug Authentication Action¶

The Debug Authentication Action can be added to any authenticator, and it will show a screen with the current attributes of your authentication transaction. It can be added multiple times, so that you can see what happens with the attributes after each authentication action. If it's put last in the chain it will show you the output of the authenticator. This is very useful to be able to find the attributes you need when issuing claims. To install the action, download the latest release from the Curity github, and put the jar-file in $IDSVR_HOME/usr/share/plugins/lib/debug-action on all nodes (including admin), and restart Curity.

Creating the action¶

After restarting, you will have a new authentication action available.

Adding the action to an authenticator¶

In this screenshot, the action has been added to an authenticator with an action that performs a lookup for additional attributes in a data source, and then runs the debug action to show us the attributes.

Running the authentication flow¶

When an authentication flow is run, the last step will be a screen like this:

Here we see all the current subject attributes in the authentication transaction, together with the Context Attributes, which could be picked up using the Context Attributes provider. We also see that there is no email attribute, but there is emails which could be used instead if the formatting is a bit different.

Transforming the claim¶

Since this data source outputed the single email as a SCIM-style list, some scripting is needed to get the actual value to put into the claim. This is done in the Transformation column of the claims configuration.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

function transform(attributes) {
  //Transform the attributes and return the appropriate value for the claim
  if(attributes.emails !== undefined 
      && attributes.emails.length > 0
      && attributes.emails[0].value !== null) {

      return attributes.emails[0].value;
  }
  return null;
}

With this configuration, theemail claim will now be added to the ID token, using the value of the first email that can be found in the emails attribute from the authenticated subject.

Conclusion¶

Using the Authenticated Subject claims provider, all the attributes obtained during authentication can be used to issue tokens. This is perfect when attribute lookups are already performed during authentication, as it will avoid unnecessary lookups during token issuance. If there needs to be some dynamics, or if only certain clients needs the actual claim, perhaps the Script or Data Source claims providers can be a better fit.