AdminUI's User Settings Endpoints

AdminUI provides a user interface (UI) for identity professionals to manage the claims associated with a user.

These claims may form the basis of an authorization decision they may also be used for general identity information about the user, for example, greeting name or mobile number.

If any of the less sensitive information changes, the user will need to contact the help desk to get them updated, this is less than ideal and a cost to the enterprise. Providing a self-service portal for users to manage these less sensitive claims makes sense in both customer experience and management cost.

AdminUI allows the administrators to mark claim types as user-editable. A user can then update any of these claims types associated with their account, via the user settings API.

The user settings API enables organizations to develop a self-service portal for users to manage their allowed claims. The article below lays out how to build a self-service portal.

AdminUI's User Settings Endpoints

AdminUI has two user settings endpoints - one to get the user settings, and one to update them.

In this article, we are going to run through the process of creating a web application that can be used to edit a user's claims using AdminUI's user settings endpoints.

First, I will run through creating a basic web application. After that, I will set it up to use AdminUI’s user settings endpoints. This will allow your application to act as a self-service user profile page.

Before you get started, you will need to have an IdentityServer running under HTTPS and an AdminUI instance. You can request a demo of AdminUI from identityserver.com.

Using the User Settings Endpoints

The purpose of the user settings update endpoint is to allow a user to edit their own claims. To do this, your AdminUI instance will need to be hosted somewhere that is accessible to your web application hosting the user update UI.

To access the user settings endpoints in AdminUI, you need to request an access token from IdentityServer; this must be done on behalf of the user. This access token must also include the admin_ui_public scope in order to be authorized to use the user settings endpoints.

Once you have the access token, you can then pass it as a bearer token in an authorization header on our requests to the user settings endpoints.

User Settings Endpoints

The user settings endpoints are as follows:

• GET /UserSettings/{subject}: Returns list of editable claims for the current user (types and values)
• PUT /UserSettings: Overrides all the user's current claims with the new collection via a body containing user claims

Our Swagger docs contain more information on the endpoints that are available within the AdminUI API. These can be found at the /swagger endpoint of your AdminUI API site.

Using the Sample Application

To demo using the user settings endpoints, I will be referencing a .NET Core 2.1 web app that I have created. You can download my example here.

The app we’re creating will use AdminUI's user settings endpoint to retrieve the UserEditable claims for the user that is currently logged in, and allow them to modify and update their own claims.

To set up the example app, you need to follow some initial steps:

• First, set the AuthorityUrl and AdminUIApiUrl settings in the appsettings.json to point at your IdentityServer and AdminUI API respectively.

• Next, create a web app client in AdminUI with the following settings:

  • ClientId set to usersettings-example
  • Redirect url: http://localhost:5005/signin-oidc
  • Add protected resource admin_ui_public
  • Add identity resources openid" and "profile
  • Change grant type to hybrid
  • Add client secret password

Now set up some claim types to be editable. Either create some new claim types or set some of the existing claim types to be UserEditable. These claims will then be available to be edited using the user settings endpoint.

The user management example is now ready to go. Start up the app and click Manage Claims. After logging in, you will receive the editable claims for your current user.

The code sample is fairly self-explanatory and should be able to run against any IdentityServer4 implementation that uses AdminUI. That being said, let’s dig into some of the user settings integration points.

Getting a User's Claims

Before the user can modify any of their claims, they will need to see:

• what claims they are allowed to edit, and
• the current value of each claim.

The user will need to login before you can get their claims for them. If you set SaveTokens to true in your OpenIdConnectOptions your access token will be available after login, using the GetTokenAsync() extension method on the HttpContext:

.AddOpenIdConnect(opt =>
{                 
   /* OIDC config */
   opt.SaveTokens = true;
});

You can then use the token to request the users claims from the user settings endpoint:

public async Task<List<ClaimDto>> GetUserClaims()
{
     var client = new HttpClient();

     // get the access token from the user session
     var accessToken = await httpContextAccessor.HttpContext.GetTokenAsync("access_token");

     // add access token to request as bearer authorization header
     client.SetBearerToken(accessToken);

     // request user claims from usersettings endpoint
     var getUserClaimsUrl = $"{options.AdminUIApiUrl}/UserSettings/{GetUserSubject()}";
     var response = await client.GetStringAsync(getUserClaimsUrl);

     // deserialize result and return users claims
     var responseAsModel = JsonConvert.DeserializeObject<UserClaimsDto>(response);
     return responseAsModel.Claims;
}

Updating a User's Claims

After the user has finished modifying their claims, they will want to save their changes.

The access token is required again to update the user's claims; serialize and send up the modified claims in the body of the PUT:

public async Task UpdateUserClaims(List<ClaimDto> updatedClaims)   
{
     var client = new HttpClient();

     // get the access token from the user session
     var accessToken = await httpContextAccessor.HttpContext.GetTokenAsync("access_token");

     // add access token to request as bearer authorization header
     client.SetBearerToken(accessToken);

     // serialize request body
     var body = JsonConvert.SerializeObject(new UserClaimsDto
     {
          Subject = GetUserSubject(),
          Claims = updatedClaims
     });

     // update users claims
     var result = await client.PutAsync($"{options.AdminUIApiUrl}/UserSettings", new StringContent(body, Encoding.UTF8, "application/json"));

     if (!result.IsSuccessStatusCode)
     {
            throw new Exception("Update user claims failed");
     }
}

It is important to note again that each time you call the user settings update endpoint, it will perform a bulk update of the user’s collection of claims, replacing the claims with the new values.

You should now have everything you need to set up your own user self-management app, enabling your users to manage their own claims.