User Management developer overview

In this article, we'll explore User Management from a developer's perspective, providing you with the necessary overview and references to get started.

Before you begin

Before diving in, we recommend reading the concepts article, which provides a comprehensive overview of User Management, covering its fundamental concepts and key features.

API overview

Bizzkit User Management is divided into two core APIs:

• AUTH API: This API follows the OAuth 2.0 and OpenID Connect standards and handles user authentication and token management. Clients can obtain access tokens by sending a request to the /connect/token endpoint. These tokens are used for authenticating and authorising requests across other services, ensuring secure access control.

• IAM API: The IAM (Identity and Access Management) API focuses on user and role administration. It provides endpoints for creating, updating, and managing users, roles, and permissions. This allows administrators to control access to resources, ensuring that only authorised users can perform specific actions.

These REST APIs work together to secure and manage access within the Bizzkit platform. The AUTH API handles the authentication process by issuing tokens, while the IAM API manages roles and permissions to ensure proper access control.

Obtaining an authentication token

Below is an example of how to connect to the AUTH API and retrieve a token for use with other Bizzkit APIs.

1
2
3
4
5
6

curl -X POST https://myenv-auth.bizzkit.biz/connect/token `
-H "Content-Type: application/x-www-form-urlencoded" `
-d "client_id=BizzkitClient" `
-d "client_secret=BizzkitSecret" `
-d "grant_type=client_credentials" `
-d "scope=iam/ pimapi/ damapi/ mailapi/ searchapi/ courierapi/ mailapi/"     

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

@authUrl = https://myenv-auth.bizzkit.biz
@clientId = BizzkitClient
@clientSecret = BizzkitSecret
@scopes = iam/ pimapi/ damapi/ mailapi/ searchapi/ courierapi/ mailapi/

# @name login
POST {{authUrl}}/connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id={{clientId}}
&client_secret={{clientSecret}}
&grant_type=client_credentials
&scope={{scopes}}

# Saving the bearer token for later use
### 
@authtoken={{login.response.body.access_token}}
###

Make sure to update the following details:

• URL: Adjust to fit your environment.
• ClientId and ClientSecret: These can be created using the IAM API.
• Scope: Specify the application you need access to (use the /api/downstream/ProtectedApis endpoint on the IAM API to get a list of scopes). Please note that the client must be created with the correct authentication.

The request will return an authentication token, which you can use as a bearer token for subsequent requests, along with information about expiration, accessible scopes, etc.

Using the API

The IAM API includes endpoints for managing users, roles, permissions, upstream and downstream clients, AD providers, and more. For a complete list of endpoints and models, refer to the Swagger API documentation.

Swagger API reference

Here is an example of getting all users from the API:

1
2

curl -X GET https://myenv-iam.bizzkit.biz/api/Users `
-H "Authorization: Bearer ..." `

1
2
3
4
5

# authtoken defined and initialized previously
@api = https://myenv-iam.bizzkit.biz

GET {{api}}/api/Users HTTP/1.1
Authorization: Bearer {{authtoken}} 

Using the Bizzkit .NET SDK

For easy integration with Microsoft .NET, Bizzkit offers SDK packages. These packages include auto-generated Swagger clients and a factory class to simplify authentication. They automate token renewal and provide type-safe methods for the API endpoints.

All SDK package names start with the prefix Bizzkit.Sdk., and the SDK packages incorporate the following elements:

• A client factory
• A dedicated client
• Options to configure the client factory

To access the Bizzkit NuGet packages in your preferred development environment, you need to reference the Bizzkit Partner feed. You can, for example, do this by adding a nuget.config file to your project with the following configuration:

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

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget" value="https://api.nuget.org/v3/index.json" />
    <add key="bizzkit-partner" value="https://pkgs.dev.azure.com/bizzkit-platform/7dad82b4-f2ae-4a3a-ab87-3fc791e4ea62/_packaging/bizzkit-partner-feed/nuget/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="nuget">
      <package pattern="*" />
    </packageSource>
    <packageSource key="bizzkit-partner">
      <package pattern="Bizzkit*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

This configuration clears existing package sources and adds the Bizzkit Partner feed alongside the official NuGet source.

Once the feed is configured, you can install the required NuGet package using the following command:

1

dotnet add package Bizzkit.Sdk.Iam

To simplify the authentication process, all NuGet packages associated with Bizzkit applications come with a factory class. This class streamlines the creation of an authenticated Swagger-generated client.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

using Bizzkit.Sdk.Iam;

var factory = new IamClientFactory(new IamConnectionOptions
{
    BaseUrl = "https://myenv-iam.bizzkit.biz",
    Authority = "https://myenv-auth.bizzkit.biz",
    ClientId = "BizzkitClient",
    ClientSecret = "BizzkitSecret",
    Scope = "iam/"
});

var client = await factory.CreateAuthenticatedClientAsync();

As noted earlier, the SDK client is mainly an auto-generated client based on the OpenAPI interface, meaning all methods map directly to the API.

Below is an example of retrieving all users from IAM using the SDK client (with the factory and client already created):

1
2

var users = await client.ListUsersAsync();
users.ToList().ForEach(x => Console.WriteLine(x.Email));