Skip to content

Getting started

After accessing Bizzkit Commerce Cloud, you will receive an introductory email with instructions for setting up your user management API. Follow these steps to get started with your environment. The examples provided use pure HTTP, but you can use any client, including our .NET SDK.

Authentication token

To interact with the API, it is necessary to authorise using a bearer token. This can be done by using the Auth OIDC API or the Bizzkit SDK NuGet packages. You can find examples of obtaining an authentication token in the

User Management developer overview

in both HTTP and C#.

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 you can use the /api/upstream/AzureAd/{id} PUT endpoint.

1
2
3
4
curl -X PUT https://academy2-iam.bizzkit.biz/api/upstream/AzureAd/my-azure-ad-provider `
-H 'Content-Type: application/json' `
-d '{ "clientid": "my-azure-ad-provider-clientid", "clientsecret": "my-azure-ad-provider-clientsecret", "tenantId":"tenantId", "displayName":"My AzureAD provider" }'`
-H "Authorization: Bearer ..." `

Replace ... with the authtoken.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# make sure @authToken is initialized
@iamApiUrl = https://academy2-iam.bizzkit.biz
@providerId = my-azure-ad-provider
@clientId = my-azure-ad-provider-clientid
@clientSecret = my-azure-ad-provider-clientsecret
@tenantId = tenantId    
@displayName = My AzureAD provider

PUT {{iamApiUrl}}/api/upstream/AzureAd/{{providerId}}
Authorization: Bearer {{authtoken}}
Content-Type: application/json

{
    "clientid": "{{clientId}}", 
    "clientsecret": "{{clientSecret}}",
    "tenantId": "{{tenantId}}",
    "displayName": "{{displayName}}"
}
###

Refer to the API reference for optional request properties.

Make sure you add the redirect URL to your Azure AD app registration

After setting up the upstream provider in Bizzkit User Management, you must add the redirect URL to your Azure AD app registration. This ensures that the authentication flow redirects back to the Bizzkit application correctly. The correct redirect URL will be revealed in a login error message during the first login attempt, and you can add this to your Azure AD app registration. It will follow the format: https://my-auth.bizzkit.cloud/signin-my-azure-ad-provider, where my-auth.bizzkit.cloud is the URL of your environment and my-azure-ad-provider is the id of the AD provider.

Refer to your Azure AD documentation for instructions on how to update the app registration with this redirect URL.

Client secret expiry

When creating an app in Azure AD and generating a client secret, please be aware that the secret will expire after a specified period (as indicated during creation). It is your responsibility to track the expiration date and renew the client secret in advance. To renew a client secret, use the appropriate API to update your upstream provider.

Once the AzureAD upstream provider is configured, verify its functionality by logging in with your AzureAD account. A successful login confirms the setup is complete. If you encounter an error message such as: "Problem connecting to the following provider: MyAdProvider. Contact your system administrator." Review your credentials carefully and attempt the login again. If the issue persists, please reach out to support for further assistance.

Creating an admin user

To use the IAM UI to configure access to Bizzkit products, it is necessary to create an admin user. 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 the /api/Users endpoint:

1
2
3
4
curl -X POST https://academy2-iam.bizzkit.biz/api/users `
-H 'Content-Type: application/json' `
-d '{ "email": "jd@example.com", "fullName":"Jane Doe" }'`
-H "Authorization: Bearer ..." `

Replace ... with the authtoken and take note of the user id in the response.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# @name user
# make sure @authToken is initialized
@iamApiUrl = https://academy2-iam.bizzkit.biz
@fullName = Jane Doe
@email = jd@example.com

POST {{iamApiUrl}}/api/users
Authorization: Bearer {{authtoken}}
Content-Type: application/json

{
    "email": "{{email}}", 
    "fullName": "{{fullName}}"                
}

# Saving the user id for later use
### 
@userId={{user.response.body.id}}
###

The user can then be assigned the admin role by making the following POST request to the /api/Users/{userId}/Roles endpoint.

1
2
3
4
curl -X POST https://academy2-iam.bizzkit.biz/api/users/{{userId}}/roles `
-H 'Content-Type: application/json' `
-d '{ "roleName": "admin" }'`
-H "Authorization: Bearer ..." `

Replace ... with the authtoken.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# make sure @authToken is initialized
@roleName = admin

POST {{iamApiUrl}}/api/users/{{userId}}/roles
Authorization: Bearer {{authtoken}}
Content-Type: application/json

{
    "roleName": "{{roleName}}"
}
###

Delete the initial machine client

After configuring your upstream provider, it is crucial to delete the machine client (along with its client ID and client secret) received in the introductory email. However, before deleting the machine client, make sure you have created an admin user. Failing to do so will result in being locked out of the system with no way to regain access. This machine client is intended for initial setup purposes only and should be removed as soon as possible to maintain the security of your environment. Use the API to delete the client.

Setting up downstream clients

To allow applications to authorise with IAM, it is necessary to register downstream clients. There are three different types of downstream clients. See the FAQ for tips on when each 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 the /api/downstream/MachineClient/{id} endpoint:

1
2
3
4
curl -X PUT https://academy2-iam.bizzkit.biz/api/downstream/machineclient/my-machine-client-id `
-H 'Content-Type: application/json' `
-d '{ "name": "my-machine-client-name", "clientSecret":"my-machine-client-secret", "roles": ["admin"], "scopes":  [ "iam/" ] }' `
-H "Authorization: Bearer ..." `

Replace ... with the authtoken.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# make sure @authToken is initialized
@iamApiUrl = https://academy2-iam.bizzkit.biz
@machineClientId = my-machine-client-id
@machineClientName = my-machine-client-name
@clientSecret = my-machine-client-clientsecret
@roles = [ "admin" ]
@scopes =  [ "iam/" ] 

PUT {{iamApiUrl}}/api/downstream/machineclient/{{machineClientId}}
Authorization: Bearer {{authtoken}}
Content-Type: application/json

{
    "name": "{{machineClientName}}",
    "clientSecret": "{{clientSecret}}",
    "roles": {{roles}},
    "allowedScopes": {{scopes}}
}
###

If a client secret was not provided while creating the machine client, one can be generated with the following PUT request to the /api/downstream/MachineClient/{clientId}/secrets endpoint Refer to the API reference for more information.

Interactive application

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

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

Example

To configure a machine client, the following PUT request can be made to the /api/downstream/InteractiveApplication/{id} endpoint:

1
2
3
4
curl -X PUT https://academy2-iam.bizzkit.biz/api/downstream/InteractiveApplication/my-interactive-application-id `
-H 'Content-Type: application/json' `
-d '{"name":"customer-solution","clientSecret":"customer-solution-secret","baseDomain":"customer-solution.azurewebsites.net","allowedScopes":["iam/"],"redirectUris":["https://customer-solution.azurewebsites.net/callback"]}' `
-H "Authorization: Bearer ..." `

Replace ... with the authtoken.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# make sure @authToken is initialized
@iamApiUrl = https://academy2-iam.bizzkit.biz
@interactiveApplicationId = my-interactive-application-id
@clientSecret = customer-solution-secret
@baseDomain = customer-solution.azurewebsites.net
@allowedScopes = [ "iam/" ]
@redirectUris = [ "https://customer-solution.azurewebsites.net/callback" ]

PUT {{iamApiUrl}}/api/downstream/InteractiveApplication/{{interactiveApplicationId}}
Authorization: Bearer {{authtoken}}
Content-Type: application/json

{
    "name": "customer-solution",
    "clientSecret": "{{clientSecret}}",
    "baseDomain": "{{baseDomain}}",
    "allowedScopes": {{allowedScopes}},
    "redirectUris": {{redirectUris}}
}
###

If a client secret was not provided while creating the interactive application, one can be generated with the following PUT request to /api/downstream/InteractiveApplication/my-interactive-application/secrets endpoint. The secret is returned in the HTTP response and can also be requested from the API afterwards.

Refer to the API reference for more information.

Clientside application

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

Example

To configure a machine client, the following PUT request can be made to the api/downstream/ClientsideApplication/my-clientside-application/{id} endpoint:

1
2
3
4
curl -X PUT https://academy2-iam.bizzkit.biz/api/downstream/ClientsideApplication/my-clientside-application-id `
-H 'Content-Type: application/json' `
-d '{"name":"ecommerce-search","baseDomain":"ecommercesearch.bizzkit.cloud","allowedScopes":["searchapi/"],"redirectUris":["https://ecommercesearch.bizzkit.cloud/callback","https://ecommercesearch.bizzkit.cloud/swagger/oauth2-redirect.html"]}' `
-H "Authorization: Bearer ..." `

Replace ... with the authtoken.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# make sure @authToken is initialized
@iamApiUrl = https://academy2-iam.bizzkit.biz
@clientsideApplicationId = my-clientside-application-id
@name = ecommerce-search
@baseDomain = ecommercesearch.bizzkit.cloud
@allowedScopes = [ "searchapi/" ]
@redirectUris = [ "https://ecommercesearch.bizzkit.cloud/callback", "https://ecommercesearch.bizzkit.cloud/swagger/oauth2-redirect.html" ]

PUT {{iamApiUrl}}/api/downstream/ClientsideApplication/{{clientsideApplicationId}}
Authorization: Bearer {{authtoken}}
Content-Type: application/json

{
    "name": "{{name}}",
    "baseDomain": "{{baseDomain}}",
    "allowedScopes": {{allowedScopes}},
    "redirectUris": {{redirectUris}}
}
###

Refer to the API reference for more information.

Conclusion

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