Skip to content

Getting started

Access Environment

Once you have been onboarded to BCC, you will receive an introduction email with details on how to access your user management API for the first time.

To interact with the user management API, it is necessary to authorize using a bearer token. This can be done by using Bizzkit SDK nuget packages or manually by using the Auth OIDC API.

For more information about the user management API, see the API reference. The recommended method of acquiring authorization for the Bizzkit API is to use Bizzkit SDK clients.

Each SDK client has a ConnectionOptions configuration object, which can be used to configure the authorization of the client. Automatic renewal of authorization tokens is included in the SDK client.

For authorizing using the IAM SDK, the IamConnectionOptions can be configured:

1
2
3
4
5
6
var opts = new IamConnectionOptions{
    Authority = "https://my-auth.bizzkit.cloud",
    BaseUrl = "https://my-iam.bizzkit.cloud",
    ClientId = "my-client-id",
    ClientSecret = "my-client-secret"
};

An API client can then be retrieved by creating a client factory with the authentication configuration:

1
2
var fac = new IamClientFactory(opts);
var client = await fac.CreateAuthenticatedClientAsync();

Bizzkit Auth implements the OIDC standard. To obtain an access token with client credentials, the following POST request can be made to https://my-auth.bizzkit.cloud/connect/token. The request body must use the Content-Type: application/x-www-form-urlencoded:

1
2
3
4
grant_type:client_credentials
audience:iam/
client_id:my-client-id
client_secret:my-client-secret

The returned access token can then be used to authorize API requests by adding Authorization: Bearer {token} to HTTP request headers.

Setting up an upstream provider

In order to sign in to Bizzkit User Management, you must configure one or more upstream providers. Several types of upstream providers are supported:

  • AzureAd
  • Google
  • Auth0

Each provider type has a corresponding set of endpoints to manage providers.

Example

To configure an AzureAd upstream provider, the following PUT request can be made to https://my-iam.bizzkit.cloud/api/upstream/AzureAd/my-azure-ad-provider, where my-azure-ad-provider is a name of your choice:

1
2
3
4
5
6
{
    "tenantId": "provider-tenant-id",
    "clientId": "provider-client-id",
    "clientSecret": "provider-client-secret",
    "displayName": "My AzureAD provider"
}

Refer to the API reference for optional request properties.

Creating an admin user

To be able to use the IAM UI to configure access to Bizzkit products, it is necessary to create an admin user client. This can be done by creating a user through the API and assigning it the admin role.

Example

To create a user for Jane Doe, the following POST request can be made to https://my-iam.bizzkit.cloud/api/Users:

1
2
3
4
5
{
    "email": "jd@example.com",
    "userName": "jd@example.com",
    "fullName": "Jane Doe"
}

Take note of the user id in the response. The user can then be assigned the admin role by making the following POST request to https://my-iam.bizzkit.cloud/api/Users/<user-id>/Roles, where <user-id> is replaced with the id from the response above:

1
2
3
{
    "roleName": "admin"
}

Setting up downstream clients

To allow applications to authorize with IAM, it is necessary to register downstream clients.

There are three different types of downstream clients. See the FAQ for tips on when which client type is appropriate.

Machine Client

Machine clients are used to allow automated system-to-system API access.

To configure a machine client, a list of allowed scopes is provided, limiting which APIs the machine client can access.

A machine client can be created with a specific client secret. Alternatively, Bizzkit user management can be used to generate a secure client secret.

Example

To configure a machine client, the following PUT request can be made to https://my-iam.bizzkit.cloud/api/downstream/MachineClient/my-machine-client:

1
2
3
4
5
6
{
    "name": "my-ingest-service",
    "clientSecret": "my-ingest-service-secret",
    "roles": [ "admin" ],
    "allowedScopes": [ "iam/" ]
}

If a client secret was not provided while creating the machine client, one can be generated with the following PUT request to https://my-iam.bizzkit.cloud/api/downstream/MachineClient/my-machine-client/secrets:

1
2
3
{
    "description": "Ingestion Service Secret"
}

The secret is returned in the HTTP response and can also be requested from the API afterwards.

Interactive Application

Interactive applications can be used to authorize users from a trusted application. An example of this could be cookie-based authorization.

As with the machine client, a secret is generated for the interactive application to use for authorization.

Example

To configure an interactive application, the following PUT request can be made to https://my-iam.bizzkit.cloud/api/downstream/InteractiveApplication/my-interactive-application:

1
2
3
4
5
6
7
8
9
{
    "name": "customer-solution",
    "clientSecret": "customer-solution-secret",
    "baseDomain": "customer-solution.azurewebsites.net",
    "allowedScopes": [ "iam/" ],
    "redirectUris": [
        "https://customer-solution.azurewebsites.net/callback",
    ]
}

If a client secret was not provided while creating the interactive application, one can be generated with the following PUT request to https://my-iam.bizzkit.cloud/api/downstream/InteractiveApplication/my-interactive-application/secrets:

1
2
3
{
    "description": "Customer Solution Secret"
}

The secret is returned in the HTTP response and can also be requested from the API afterward.

Clientside Application

Clientside applications can be used to authorize users from client-side applications, such as single-page applications.

Example

To configure a clientside application, the following PUT request can be made to https://my-iam.bizzkit.cloud/api/downstream/ClientsideApplication/my-clientside-application:

1
2
3
4
5
6
7
8
9
{
    "name": "ecommerce-search",
    "baseDomain": "ecommercesearch.bizzkit.cloud",
    "allowedScopes": [ "searchapi/" ],
    "redirectUris": [
        "https://ecommercesearch.bizzkit.cloud/callback",
        "https://ecommercesearch.bizzkit.cloud/swagger/oauth2-redirect.html",
    ]
}

Conclusion

Your application is now configured to allow clients of various types to authorize using traditional username-password access, or by relying on upstream providers.