How to configure AzureAD
Follow this step-by-step guide to configure the integration between Port and Azure Active Directory.
In order to complete the process you will need to contact us to receive the information you require, as well as the information Port requires from you. Read below for more information.
Port-AzureAd integration benefits
- Connect to the Port application via an AzureAD app.
- Your AzureAD teams will be automatically synced with Port upon a user sign-in.
- Set granular permissions on Port according to your AzureAD groups.
How to configure a Port application in Azure AD
Prerequisites
To make the Port app connection work, users who have access need to have a legal value in their Email
field in Azure AD.
Step #1: Register a new application
-
In the Microsoft Azure Portal, go to
Azure Active Directory
. -
Click on
App registrations
. -
Click on
New registration
at the top of the page -
Define the Port application settings:
4.1
Name
: Insert a friendly name for the Port app, likePort
.4.2
Supported account types
: Please select the option that is appropriate for your organization.noteFor most use cases this would be Accounts in this organizational directory only (Default Directory only - Single tenant).
4.3
Redirect URI
:- Set
Platform
toWeb
. - Set
URL
tohttps://auth.getport.io/login/callback
.
4.4 Click
Register
.4.5 On the new Port App page, click
Authentication
.4.6
Front-channel logout URL
: paste the following URL:https://auth.getport.io/logout
single sign-outAdding the front-channel logout URL will enable single sign-out, meaning when a user logs our from Port, it also logs him out from his identity provider.
4.7 Click
Save
. - Set
Step #2: Customize your Port app with Login URL and Logo
-
On the new Port App page, click
Branding & Properties
.1.1
Home page URL
: paste the following URL:https://auth.getport.io/authorize?response_type=token&client_id=96IeqL36Q0UIBxIfV1oqOkDWU6UslfDj&connection={CONNECTION_NAME}&redirect_uri=https%3A%2F%2Fapp.getport.io
noteWe will provide your
{CONNECTION_NAME}
(Contact us on Slack/Intercom).1.2 Add the Port logo (optional):
1.3
Publisher domain
: Select the domain matching your user emails (for examplegetport.io
).1.4 Click
Save
.
Step #3: Configuring the application permissions
-
On the Port App page, click
API Permissions
. -
Click
Add a permission
: -
On the
Microsoft APIs
tab:3.1 Click on
Microsoft Graph
3.2 Click on
Delegate Permissions
3.3 Search and mark the following permissions:
email
,openid
,profile
,User.read
.
3.4 Click
Add permissions
.note(OPTIONAL)
Grant admin consent
: when users from your organization will first log in, they will be prompted to confirm the permissions specified here. You can click theGrant admin consent for Default Directory
to automatically approve their permissions.
Step #4: Configuring the application claims
-
On the Port App page, click
Token configuration
: -
Click
Add optional claim
: -
Select
ID
as the token type and then select theemail
claim, then clickAdd
:noteRepeat the same process for
Access
andSAML
(3 times total). -
Your optional claims will look like this:
infoIf you wish to configure the
groups claim
to pull your AzureAD groups into Port, please follow How to allow pulling AzureAD groups to Port.
Step #5: Configuring application secret
-
On the Port App page, click
Certificates & Secrets
: -
On the
Client secrets
tab, click theNew client secret
button:2.1
Description
: Enter a secret description, for examplePort Login Client Secret
.2.2
Expires
: Select when will the secret expires.dangerBe sure to mark on your calendar the expiration date of the secret. The secret needs to be replaced before its expiration, otherwise login to Port will be disabled.
2.3 Click
Add
.A secret will be created and its Value will appear as shown in the image below. Immediately document the secret’s value because we will need it for our next step.
COPY YOUR SECRET NOWBe advised that your secret will never appear again after you leave this page.
Step #6: Providing the application information to Port
Port needs the following information for this process:
- The
Client Secret
value that you created on Step 5: Configuring application secret. - The
Application (Client) ID
, which appears on the Port application overview page:
Port will provide you the CONNECTION_NAME
needed for the homepage URL of the App, as described on Step 2.
Step #7: Exposing the application to your organization
-
Assigning the App to organization users and groups
After the app setup is complete, you can proceed to assign it to your organization’s users and groups, by distributing it in your organization:
1.1 Go to
Azure Active Directory
.1.2 Go to
Enterprise Applications
: -
Click on the Port app:
-
Click on
Users and Groups
: -
Click
Add user/group
:4.1 Select users and groups you want to grant access to Port.
4.2 Click
Assign
. -
Make the Port application visible on the
myapplications
page:5.1 Go to
Azure Active Directory
.5.2 Go to
Enterprise Applications
.5.3 Click on the Port app.
5.4 Click on
Properties
:5.5 Set the application properties:
-
Mark
Enabled for users to sign-in?
asYes
. -
Mark
Visible to users?
asYes
.
noteBy default the
Assignment required?
flag is set toNo
, meaning any user with the Homepage URL to the Port app can access it, even if the app isn’t directly assigned to them. Changing the flag toYes
means only users and groups the app is directly assigned to can use and access it.You should see the Port app on the https://myapplications.microsoft.com dashboard:
noteUsers can also manually access Port by going to the App Homepage URL:
https://auth.getport.io/authorize?response_type=token&client_id=96IeqL36Q0UIBxIfV1oqOkDWU6UslfDj&connection={CONNECTION_NAME}&redirect_uri=https%3A%2F%2Fapp.getport.io
-
Permissions required to pull AzureAD groups to Port
Port can query the group membership of users who log in through the AzureAD SSO, and add their teams as team entities inside Port. This allows the platform engineers to take advantage of both existing groups from AzureAD and teams created manually inside Port to manage permissions and access to resources inside Port's catalog.
Important: In order to import Azure AD groups into Port, Port will require the connection app to approve the Directory.Read.All
permission