Luware Knowledge

Nimbus Portal Nimbus Admin Release Notes Service Status
Home Nimbus Nimbus Integrations

Nimbus API

Provisioning via REST API

The Nimbus Public REST API allows to provision blank users. This page describes the setup and usage procedures.

PRECONDITIONS

On this page the following topics are covered: 

  1. Check if the API was enabled on your Provisioning Tenant Settings. This feature is enabled by a Luware System Administrator. 
  2. Set up the Nimbus App Registration and necessary API Permissions in Azure. 
    As a Tenant Administrator you can perform these steps below in parallel.
 

Step 1 - Azure Setup

✅ Tenant Administrator: The following steps need to be done with Tenant Administrator privileges. You will grant some of the Nimbus App Permissions to be used later via the API.

Create App registration

🔎 Also see: Quickstart: Register an application with the Microsoft identity platform | Microsoft Learn

  1. Go to Portal.Azure.com
  2. In your Tenant, Create an App registration, e.g. “My Nimbus App” 
  3. Leave the other options as they are.
Nimbus App Registration

Grant API Web Access Permissions

🔎 Also see: Configure an app to access a web API - Microsoft identity platform | Microsoft Learn

✅ Tenant Administrator:  Note that a Nimbus App must be registered at this point.

  1. Go to "API Permissions"
  2. Request new API permission by clicking “Add a permission”. 
  3. Search for "Luware"
  4. Select the entry “Luware Nimbus Login” from your Nimbus App
  5. Select Application Permissions
  6. Select the following role permissions: 
    1. "Provisioning.User.Create" . 
    2. “Provisioning.User.Delete”. 💡Note that this optional. Deletion via API is not supported yet.
  7. Back In API Permissions, click  “Grant Admin Consent for Luware AG” → Green Checkboxes signal the successful permission grant.
Successfully granted API permissions (User.Create and User.Delete)

Authentication 

There are multiple ways to authenticate with your newly created Azure Application. The method of authentication doesn't really matter for Nimbus and depends on your Use Case and external system. We therefore only add some general recommendations and point to the Microsoft Documentation.

Public Client Application

🔎 From: Public client and confidential client applications | Microsoft Learn 

Public client applications run on devices, such as desktop, browserless APIs, mobile or client-side browser apps. They can't be trusted to safely keep application secrets, so they can only access web APIs on behalf of the user. Anytime the source or compiled bytecode of a given app is transmitted anywhere it can be read, disassembled, or otherwise inspected by untrusted parties, it's a public client. As they also only support public client flows and can't hold configuration-time secrets, they can't have client secrets.

🔎 From: Public client and confidential client applications | Microsoft Learn 

After determining the type of client application you're building, you can decide whether to enable the public client flow in your app registration. By default, allow public client flow in your app registration should be disabled unless you or your developer are building a public client application and using the following OAuth authorization protocol or features:

OAuth Authorization protocol/Feature Type of public client application Examples/notes
Native Authentication Microsoft Entra External ID application that requires full customization of the user interface, including design elements, logo placement, and layout, ensuring a consistent and branded look. Note: Native Authentication is only available for app registrations in Microsoft Entra External ID tenants. Learn more here
Device code flow Applications that run on input-constrained devices such as a smart TV, IoT device, or a printer  
Resource owner password credential flow Applications that handles passwords users enter directly, instead of redirecting users to Entra hosted login website and letting Entra handle user password in a secure manner. Microsoft recommends you do not use the ROPC flow. In most scenarios, more secure alternatives, such as the Authorization code flow, are available and recommended.
Windows Integrated Auth Flow Desktop or mobile applications running on Windows or on a machine connected to a Windows domain (Microsoft Entra ID or Microsoft Entra joined) using Windows Integrated Auth Flow instead of Web account manager A desktop or mobile application that should be automatically signed in after the user has signed into the windows PC system with a Microsoft Entra credential
 
 

Confidential Client Application / Client Secret

🔎 From: Quickstart: Register an application with the Microsoft identity platform | Microsoft Learn

Sometimes called an application password, a client secret is a string value your app can use in place of a certificate to identify itself.

Client secrets are considered less secure than certificate credentials. Application developers sometimes use client secrets during local app development because of their ease of use. However, you should use certificate credentials for any of your applications that are running in production.

 
  1. Select your previously registered Nimbus App.
  2. Go to Certificates & secrets > Client secrets > New client secret.
  3. Add a description for your client secret.
  4. Select an expiration for the secret or specify a custom lifetime. 
  5. Click Add.
  6. 🧠 Record the Secret's value for later use within the Nimbus API.
    ☝This secret value is never displayed again after you leave this page.

 From: Public client and confidential client applications | Microsoft Learn 

Confidential client applications run on servers, such as web apps, web API apps, or service/daemon apps. They're considered difficult to access by users or attackers, and therefore can adequately hold configuration-time secrets to assert proof of its identity. The client ID is exposed through the web browser, but the secret is passed only in the back channel and never directly exposed.

 
 

Step 2 - Configure Nimbus

✅Checklist:

🧠 For the next steps in Nimbus you will need the Application ID of your previously registered Nimbus Application.

 
  1. Log into Nimbus Admin Portal.
  2. Go to Tenant Administration  > Provisioning Tenant Settings > “Application Permissions”.
  3. Click on “Add”. 
  4. Fill in the 🧠 Azure Application ID from → Chapter: Step 1 above.
  5. Define the Organization Units scope under which the Nimbus API will have access. 
  6. Save and Close. 
  7. Still within Admin Portal, Go to the Configuration (Admin) > Organization Units
  8. Open your Organization Unit Entry and note the GUID in the browser address bar as follows. 
    🧠 Repeat this step and note down any OU ID you wanna create users in later using the API.
Identifying the Organization Unit IDs for later API usage

Step 3 - Using the API

Now your API should be ready to use and create empty users. 

💡In this example we authenticate using a Confidential Client Application using Client Credentials. Of course you can use any other means of authentication as described in → Chapter: Step 1 > Authentication above.

✅Checklist:

  • 🧠You will need the Nimbus Application ID and the Secret of your App
  • 🧠You also need the Organization Units ID to make API calls
  • ✅ Additionally, you need the O365 IDs of the (future) users you want to provision.
 
  1. Create token using OAuth 2.0. For example, to get a token using Client Credentials, choose the following:
  2. Grant type: Client Credentials
  3. Access token URL: https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/token1
  4. Client ID: 🧠 Application ID of your app
  5. Client Secret: 🧠 As created in your app
  6. Scope: http://portal.{geography}-{number}.luware.cloud/.default2
  7. Client Authentication: Send as Basic Auth header

Footnotes

 1 Head to your Tenant Administration and check the URL in the browser address bar. Look for the part starting with “tenantId=”  tenantId=9fce70af-a632-49ca-bc0d-53db5a21c5b3

2 The Portal URL depends on the geographical location of your Nimbus Cluster. When you log into Nimbus Portal you will be redirected to the right cluster. Check the Access URL list below as a reference.

INC Nimbus Portal URLs

Switzerland 01 https://portal.ch-01.luware.cloud/
Switzerland 02 https://portal.ch-02.luware.cloud/
Germany 01 https://portal.dewe-01.luware.cloud/
Germany 02 https://portal.dewe-02.luware.cloud/
United Kingdom 01 https://portal.ukso-01.luware.cloud/
Australia 01 https://portal.aue-01.luware.cloud/
West Europe 01 https://portal.euwe-01.luware.cloud/
East United States 01 https://portal.use-01.luware.cloud/
Nimbus Portal URLs

✅ Make sure to configure your web proxies to allow access to these domains or whitelist the complete *.luware.cloud domain.

 

POST New Empty User

POST https://admin.{geography}-{number}/api/public-api-next/user

Note

The Admin URL depends on the geographical location of your Nimbus Cluster. When you log into Nimbus Portal you will be redirected to the right cluster. Check the Access URL list below as a reference.

💡Example Connector URL: https://admin.ch-01.luware.cloud/api/public-api-next/user

Note that this URL depends on the Nimbus Cluster where your Tenant is stored. Observe your URL after logging into the Admin Portal.

INC Nimbus Admin URLs

Switzerland 01 https://admin.ch-01.luware.cloud/
Switzerland 02 https://admin.ch-02.luware.cloud/
Germany 01 https://admin.dewe-01.luware.cloud/
Germany 02 https://admin.dewe-02.luware.cloud/
United Kingdom 01 https://admin.ukso-01.luware.cloud/
Australia 01 https://admin.aue-01.luware.cloud/
West Europe 01 https://admin.euwe-01.luware.cloud/
East United States 01 https://admin.use-01.luware.cloud/
Nimbus Admin Panel URL

✅ Make sure to configure your web proxies to allow access to these domains or whitelist the complete *.luware.cloud domain.

 

Body

✅ You require the O365 ID of the user and the 🧠 OrganizationUnit ID from the (permitted) OU (→ Chapter: Step 2 above)

{
 "o365Id": "<guid>",
 "organizationUnitId": "<guid>"
}

Additional API Notes

Notes

Rate Limit: There is a limit of 60 API operations/minute. The API will delay processing if this threshold is exceeded.

 
Use Case - Exposing an API via Microsoft Entra ID

In this use case, we handle the scenario where you want to communicate with Assis...

Extensions Tenant Settings

🔍 Here you can configure all additional Nimbus extensions and separately enabled ...

Table of Contents