Create Microsoft Entra app registration for use with CycleCloud (PREVIEW)

Microsoft Entra ID is a cloud-based identity and access management service that enables your employees to access external resources. If your organization requires the use of Microsoft Entra ID, CycleCloud provides a native integration to Microsoft Entra ID for user management, authorization, and authentication.

Creating the CycleCloud app registration

1. In the Azure portal, select the Microsoft Entra ID icon in the navigation pane. Or, type "Microsoft Entra ID" in the search bar and select "Microsoft Entra ID" from the Services category in the results.

2. Go to the App registrations tab.
   

3. Select New registration from the top menu and set up your application. You don't need to set the redirect URI right now.

4. On the Overview page of your newly created application, note the Application (client) ID and Directory (tenant) ID fields. You need these values later to configure Entra authentication in CycleCloud.

5. On the Expose an API page of your app, select Add a scope. This step exposes your app registration as an API for which Access Tokens can be generated. In the pop-up, keep the Application ID URI as the default value, which should look like api://{ClientID}.

6. When you select Save and Continue, the portal prompts you to configure the new scope. Enter user_access as the scope name. Configure the other fields as you want, but set State to Enabled. After you save the scope, it appears in the Scopes table.

7. Go to the API Permissions page and select Add a permission. In the Request API permissions menu, go to My APIs and choose the name of your application. From there, choose Delegated permissions and select the scope you just created. Select Add permission. Your new permission now appears in the Configured permissions table.

8. On the Authentication page, select Add a platform and choose Single-page application. If you plan to use the CycleCloud CLI with Entra ID, set Allow public client flows to true.

9. Under the Configure single-page application menu, set Redirect URI to "https://{your_cyclecloud_IP_or_DOMAIN_NAME}/home". You can leave the rest of fields blank.

10. Under Configure single-page application, set the Redirect URI to http://localhost. This URI is required. For more information, see Redirect URI (reply URL) restrictions and limitations. Make sure to also include both https://{your_cyclecloud_IP_or_DOMAIN_NAME}/home and https://{your_cyclecloud_IP_or_DOMAIN_NAME}/login as allowed redirect URLs. You can leave the rest of fields blank.

11. To allow multiple CycleCloud installations or multiple URIs for the same CycleCloud to access this Application Registration, configure additional URIs on the same Authentication page. Select Add URI to create a field, enter the additional URI in the new field, and select Save.

12. To enable the CycleCloud CLI to authenticate with the new application registration, add the Mobile and desktop applications platform. Go back to the Authentication page, select Add a platform again, and select Mobile and desktop applications in the Configure Desktop + Devices pop-up. Add a custom redirect URI with the value http://localhost.

    

    When you select Configure, you can also add a URI for https://localhost.

13. Next, add the user roles for CycleCloud under App roles by selecting Create app role. You can set the Display name field to anything you want, but the Value field must match the built-in CycleCloud role for this to work.

    Note

    Since Microsoft Entra ID doesn't allow roles to have spaces in them and some of the in-built CycleCloud roles include spaces (for example, “Cluster Administrator”), replace any spaces in the role names you define in Microsoft Entra ID with a dot (for example, “Data Admin” becomes “Data.Admin”). Rename any roles defined in CycleCloud to not feature dots. Role definitions in Microsoft Entra ID are case insensitive.

    At a minimum, add the following roles:

14. By default, the app registration issues access tokens v2.0, which CycleCloud doesn't support. To configure the app registration to issue tokens v1.0, select Manifest, locate the property accessTokenAcceptedVersion in the manifest, and change the value of that property to null. After changing the token version, select Save.

Permissioning users for CycleCloud

1. After you create the required CycleCloud roles, add users and assign roles to them. To do this step, go to the app's Enterprise Application page. The easiest way to get there is through a helper link on your App roles page.
2. To add a user and assign a role, go to the Users and groups page of the Enterprise Application and select Add user/group.
3. On the Add Assignment page, select one or more users and the role to assign to them. You can use a search bar to filter users. Since only one app role was created in the screenshot, it's selected automatically, but the menu for selecting it is similar to how you select users. You can assign only one role at a time. To add multiple roles to the same user, repeat this process.
4. After you assign the role, the user appears on the User and groups page. Assigning multiple roles to a single user results in several entries for that user - one entry per role.
5. RECOMMENDED: If you want to allow access to CycleCloud only for users you explicitly add to your app, go to the Properties of the Enterprise Application and set Assignment Required to Yes