Configure SAML-based single sign-on for your application using Microsoft Graph
Article
Single sign-on (SSO) is an authentication method that allows users to sign in to one application and then access multiple applications without needing to sign in again. Microsoft Entra supports various SSO methods, including OpenID Connect, OAuth, Security Assertion Markup Language (SAML), password-based, and linked SSO. Using Microsoft Graph, you can automate the configuration of SSO for your application.
In this tutorial, you learn how to:
Identify SAML-based apps in the Microsoft Entra gallery and configure SAML-based SSO for an app
Add app roles to an application and grant them to users
Configure claims to emit in the SAML token
Configure a certificate for federated SSO
Retrieve the Microsoft Entra ID SAML metadata for your application that you use to complete the integration
Prerequisites
Sign in to an API client such as Graph Explorer as a user with Cloud Application Administrator role in your Microsoft Entra tenant.
Grant yourself the following delegated permissions: Application.ReadWrite.All, AppRoleAssignment.ReadWrite.All, Policy.Read.All, Policy.ReadWrite.ApplicationConfiguration, and User.ReadWrite.All.
Have a test user to assign to the application.
Step 1: Identify the application to configure
Microsoft Entra ID has a gallery that contains thousands of preintegrated applications that you can use as a template for your application. In Microsoft Graph, this list is available through the applicationTemplate entity.
In this step, you identify the application template for the AWS IAM Identity Center (successor to AWS Single Sign-On) application that you want to configure. Record its id.
GET https://graph.microsoft.com/v1.0/applicationTemplates?$filter=displayName eq 'AWS IAM Identity Center (successor to AWS Single Sign-On)'
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ApplicationTemplates.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "displayName eq 'AWS IAM Identity Center (successor to AWS Single Sign-On)'";
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphapplicationtemplates "github.com/microsoftgraph/msgraph-sdk-go/applicationtemplates"
//other-imports
)
requestFilter := "displayName eq 'AWS IAM Identity Center (successor to AWS Single Sign-On)'"
requestParameters := &graphapplicationtemplates.ApplicationTemplatesRequestBuilderGetQueryParameters{
Filter: &requestFilter,
}
configuration := &graphapplicationtemplates.ApplicationTemplatesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
applicationTemplates, err := graphClient.ApplicationTemplates().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ApplicationTemplateCollectionResponse result = graphClient.applicationTemplates().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "displayName eq 'AWS IAM Identity Center (successor to AWS Single Sign-On)'";
});
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\ApplicationTemplates\ApplicationTemplatesRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new ApplicationTemplatesRequestBuilderGetRequestConfiguration();
$queryParameters = ApplicationTemplatesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "displayName eq 'AWS IAM Identity Center (successor to AWS Single Sign-On)'";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->applicationTemplates()->get($requestConfiguration)->wait();
Import-Module Microsoft.Graph.Applications
Get-MgApplicationTemplate -Filter "displayName eq 'AWS IAM Identity Center (successor to AWS Single Sign-On)'"
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.application_templates.application_templates_request_builder import ApplicationTemplatesRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = ApplicationTemplatesRequestBuilder.ApplicationTemplatesRequestBuilderGetQueryParameters(
filter = "displayName eq 'AWS IAM Identity Center (successor to AWS Single Sign-On)'",
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.application_templates.get(request_configuration = request_configuration)
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applicationTemplates",
"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET applicationTemplates?$select=categories,description",
"value": [
{
"id": "21ed01d2-ec13-4e9e-86c1-cd546719ebc4",
"displayName": "AWS IAM Identity Center (successor to AWS Single Sign-On)",
"homePageUrl": "https://aws.amazon.com/",
"supportedSingleSignOnModes": [
"saml",
"external"
],
"supportedProvisioningTypes": [
"sync"
],
"logoUrl": "https://galleryapplogos1.azureedge.net/app-logo/awssinglesignon_FC86917E_215.png",
"categories": [
"developerServices",
"itInfrastructure",
"security",
"New"
],
"publisher": "Amazon Web Services, Inc.",
"description": "Federate once to AWS IAM Identity Center (successor to AWS Single Sign-On) & use it to centrally manage access to multiple AWS accounts and IAM Identity Center enabled apps. Provision users via SCIM."
}
]
}
Step 2: Instantiate the application
Using the id value for the application template, create an instance of the application in your tenant. Here, you name the application AWS Contoso. The response includes an application and service principal object for AWS Contoso, which is an instance of the AWS IAM Identity Center (successor to AWS Single Sign-On) app. Record the IDs of the two objects for use later in this tutorial.
POST https://graph.microsoft.com/v1.0/applicationTemplates/21ed01d2-ec13-4e9e-86c1-cd546719ebc4/instantiate
Content-type: application/json
{
"displayName": "AWS Contoso"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.ApplicationTemplates.Item.Instantiate;
var requestBody = new InstantiatePostRequestBody
{
DisplayName = "AWS Contoso",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ApplicationTemplates["{applicationTemplate-id}"].Instantiate.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphapplicationtemplates "github.com/microsoftgraph/msgraph-sdk-go/applicationtemplates"
//other-imports
)
requestBody := graphapplicationtemplates.NewInstantiatePostRequestBody()
displayName := "AWS Contoso"
requestBody.SetDisplayName(&displayName)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
instantiate, err := graphClient.ApplicationTemplates().ByApplicationTemplateId("applicationTemplate-id").Instantiate().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.applicationtemplates.item.instantiate.InstantiatePostRequestBody instantiatePostRequestBody = new com.microsoft.graph.applicationtemplates.item.instantiate.InstantiatePostRequestBody();
instantiatePostRequestBody.setDisplayName("AWS Contoso");
var result = graphClient.applicationTemplates().byApplicationTemplateId("{applicationTemplate-id}").instantiate().post(instantiatePostRequestBody);
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\ApplicationTemplates\Item\Instantiate\InstantiatePostRequestBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new InstantiatePostRequestBody();
$requestBody->setDisplayName('AWS Contoso');
$result = $graphServiceClient->applicationTemplates()->byApplicationTemplateId('applicationTemplate-id')->instantiate()->post($requestBody)->wait();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.applicationtemplates.item.instantiate.instantiate_post_request_body import InstantiatePostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = InstantiatePostRequestBody(
display_name = "AWS Contoso",
)
result = await graph_client.application_templates.by_application_template_id('applicationTemplate-id').instantiate.post(request_body)
In this step, you configure SSO for both the AWS Contoso application and the service principal. For the application, you configure the SAML URLs while for the service principal, you set the SSO mode to saml.
Step 3.1: Set single sign-on mode for the service principal
Set saml as the SSO mode for the service principal you created in Step 2. The request returns a 204 No Content response code.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new ServicePrincipal
{
PreferredSingleSignOnMode = "saml",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals["{servicePrincipal-id}"].PatchAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewServicePrincipal()
preferredSingleSignOnMode := "saml"
requestBody.SetPreferredSingleSignOnMode(&preferredSingleSignOnMode)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
servicePrincipals, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Patch(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ServicePrincipal servicePrincipal = new ServicePrincipal();
servicePrincipal.setPreferredSingleSignOnMode("saml");
ServicePrincipal result = graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").patch(servicePrincipal);
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ServicePrincipal;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ServicePrincipal();
$requestBody->setPreferredSingleSignOnMode('saml');
$result = $graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->patch($requestBody)->wait();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ServicePrincipal(
preferred_single_sign_on_mode = "saml",
)
result = await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').patch(request_body)
In this step, set the web/redirectUris and web/redirectUris for the application you created in Step 2. The request returns a 204 No Content response code.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Application
{
IdentifierUris = new List<string>
{
"https://signin.aws.amazon.com/saml",
},
Web = new WebApplication
{
RedirectUris = new List<string>
{
"https://signin.aws.amazon.com/saml",
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Applications["{application-id}"].PatchAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewApplication()
identifierUris := []string {
"https://signin.aws.amazon.com/saml",
}
requestBody.SetIdentifierUris(identifierUris)
web := graphmodels.NewWebApplication()
redirectUris := []string {
"https://signin.aws.amazon.com/saml",
}
web.SetRedirectUris(redirectUris)
requestBody.SetWeb(web)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
applications, err := graphClient.Applications().ByApplicationId("application-id").Patch(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Application application = new Application();
LinkedList<String> identifierUris = new LinkedList<String>();
identifierUris.add("https://signin.aws.amazon.com/saml");
application.setIdentifierUris(identifierUris);
WebApplication web = new WebApplication();
LinkedList<String> redirectUris = new LinkedList<String>();
redirectUris.add("https://signin.aws.amazon.com/saml");
web.setRedirectUris(redirectUris);
application.setWeb(web);
Application result = graphClient.applications().byApplicationId("{application-id}").patch(application);
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Application;
use Microsoft\Graph\Generated\Models\WebApplication;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new Application();
$requestBody->setIdentifierUris(['https://signin.aws.amazon.com/saml', ]);
$web = new WebApplication();
$web->setRedirectUris(['https://signin.aws.amazon.com/saml', ]);
$requestBody->setWeb($web);
$result = $graphServiceClient->applications()->byApplicationId('application-id')->patch($requestBody)->wait();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.application import Application
from msgraph.generated.models.web_application import WebApplication
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Application(
identifier_uris = [
"https://signin.aws.amazon.com/saml",
],
web = WebApplication(
redirect_uris = [
"https://signin.aws.amazon.com/saml",
],
),
)
result = await graph_client.applications.by_application_id('application-id').patch(request_body)
If the application requires the role information in the token, add the definition of the roles in the application object. By default, the appRoles object in the application and service principal in Step 2 included the default User and msiam_access roles. Don't modify or remove them. To add more roles, you must include both the existing roles and the new roles in the appRoles object in the request, otherwise, the existing roles are replaced.
In this step, add the Finance,WAAD and Admin,WAAD roles to the AWS Contoso service principal. The request returns a 204 No Content response code.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new ServicePrincipal
{
AppRoles = new List<AppRole>
{
new AppRole
{
AllowedMemberTypes = new List<string>
{
"User",
},
Description = "User",
DisplayName = "User",
Id = Guid.Parse("8774f594-1d59-4279-b9d9-59ef09a23530"),
IsEnabled = true,
Origin = "Application",
Value = null,
},
new AppRole
{
AllowedMemberTypes = new List<string>
{
"User",
},
Description = "msiam_access",
DisplayName = "msiam_access",
Id = Guid.Parse("e7f1a7f3-9eda-48e0-9963-bd67bf531afd"),
IsEnabled = true,
Origin = "Application",
Value = null,
},
new AppRole
{
AllowedMemberTypes = new List<string>
{
"User",
},
Description = "Admin,WAAD",
DisplayName = "Admin,WAAD",
Id = Guid.Parse("3a84e31e-bffa-470f-b9e6-754a61e4dc63"),
IsEnabled = true,
Value = "arn:aws:iam::212743507312:role/accountname-aws-admin,arn:aws:iam::212743507312:saml-provider/WAAD",
},
new AppRole
{
AllowedMemberTypes = new List<string>
{
"User",
},
Description = "Finance,WAAD",
DisplayName = "Finance,WAAD",
Id = Guid.Parse("7a960000-ded3-455b-8c04-4f2ace00319b"),
IsEnabled = true,
Value = "arn:aws:iam::212743507312:role/accountname-aws-finance,arn:aws:iam::212743507312:saml-provider/WAAD",
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals["{servicePrincipal-id}"].PatchAsync(requestBody);
You want to configure the SAML attributes by mapping the Microsoft Entra ID fields with specific AWS IAM Identity Center application attributes. You therefore create a claims mapping policy and assign it to the service principal.
Step 5.1: Create a claims mapping policy
In addition to the basic claims, configure the following claims for Microsoft Entra ID to emit in the SAML token:
Some keys in the claims mapping policy, such as Version, are case sensitive. The error message "Property has an invalid value" might be a case sensitivity issue.
Create the claims mapping policy and record its ID for use later in this tutorial.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new ClaimsMappingPolicy
{
Definition = new List<string>
{
"{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\", \"ClaimsSchema\": [{\"Source\":\"user\",\"ID\":\"assignedroles\",\"SamlClaimType\": \"https://aws.amazon.com/SAML/Attributes/Role\"}, {\"Source\":\"user\",\"ID\":\"userprincipalname\",\"SamlClaimType\": \"https://aws.amazon.com/SAML/Attributes/RoleSessionName\"}, {\"Value\":\"900\",\"SamlClaimType\": \"https://aws.amazon.com/SAML/Attributes/SessionDuration\"}, {\"Source\":\"user\",\"ID\":\"assignedroles\",\"SamlClaimType\": \"appRoles\"}, {\"Source\":\"user\",\"ID\":\"userprincipalname\",\"SamlClaimType\": \"https://aws.amazon.com/SAML/Attributes/nameidentifier\"}]}}",
},
DisplayName = "AWS Claims Policy",
IsOrganizationDefault = false,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Policies.ClaimsMappingPolicies.PostAsync(requestBody);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ClaimsMappingPolicy claimsMappingPolicy = new ClaimsMappingPolicy();
LinkedList<String> definition = new LinkedList<String>();
definition.add("{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\", \"ClaimsSchema\": [{\"Source\":\"user\",\"ID\":\"assignedroles\",\"SamlClaimType\": \"https://aws.amazon.com/SAML/Attributes/Role\"}, {\"Source\":\"user\",\"ID\":\"userprincipalname\",\"SamlClaimType\": \"https://aws.amazon.com/SAML/Attributes/RoleSessionName\"}, {\"Value\":\"900\",\"SamlClaimType\": \"https://aws.amazon.com/SAML/Attributes/SessionDuration\"}, {\"Source\":\"user\",\"ID\":\"assignedroles\",\"SamlClaimType\": \"appRoles\"}, {\"Source\":\"user\",\"ID\":\"userprincipalname\",\"SamlClaimType\": \"https://aws.amazon.com/SAML/Attributes/nameidentifier\"}]}}");
claimsMappingPolicy.setDefinition(definition);
claimsMappingPolicy.setDisplayName("AWS Claims Policy");
claimsMappingPolicy.setIsOrganizationDefault(false);
ClaimsMappingPolicy result = graphClient.policies().claimsMappingPolicies().post(claimsMappingPolicy);
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.claims_mapping_policy import ClaimsMappingPolicy
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ClaimsMappingPolicy(
definition = [
"{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\", \"ClaimsSchema\": [{\"Source\":\"user\",\"ID\":\"assignedroles\",\"SamlClaimType\": \"https://aws.amazon.com/SAML/Attributes/Role\"}, {\"Source\":\"user\",\"ID\":\"userprincipalname\",\"SamlClaimType\": \"https://aws.amazon.com/SAML/Attributes/RoleSessionName\"}, {\"Value\":\"900\",\"SamlClaimType\": \"https://aws.amazon.com/SAML/Attributes/SessionDuration\"}, {\"Source\":\"user\",\"ID\":\"assignedroles\",\"SamlClaimType\": \"appRoles\"}, {\"Source\":\"user\",\"ID\":\"userprincipalname\",\"SamlClaimType\": \"https://aws.amazon.com/SAML/Attributes/nameidentifier\"}]}}",
],
display_name = "AWS Claims Policy",
is_organization_default = False,
)
result = await graph_client.policies.claims_mapping_policies.post(request_body)
POST https://graph.microsoft.com/v1.0/servicePrincipals/ef04fead-8549-4e59-b5f7-d1d8c697ec64/claimsMappingPolicies/$ref
Content-type: application/json
{
"@odata.id": "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/92037c7a-a875-49a0-814e-8ec30f880e2e"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new ReferenceCreate
{
OdataId = "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/92037c7a-a875-49a0-814e-8ec30f880e2e",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.ServicePrincipals["{servicePrincipal-id}"].ClaimsMappingPolicies.Ref.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewReferenceCreate()
odataId := "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/92037c7a-a875-49a0-814e-8ec30f880e2e"
requestBody.SetOdataId(&odataId)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").ClaimsMappingPolicies().Ref().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.models.ReferenceCreate referenceCreate = new com.microsoft.graph.models.ReferenceCreate();
referenceCreate.setOdataId("https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/92037c7a-a875-49a0-814e-8ec30f880e2e");
graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").claimsMappingPolicies().ref().post(referenceCreate);
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ReferenceCreate;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ReferenceCreate();
$requestBody->setOdataId('https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/92037c7a-a875-49a0-814e-8ec30f880e2e');
$graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->claimsMappingPolicies()->ref()->post($requestBody)->wait();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.reference_create import ReferenceCreate
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ReferenceCreate(
odata_id = "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/92037c7a-a875-49a0-814e-8ec30f880e2e",
)
await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').claims_mapping_policies.ref.post(request_body)
After you add the certificate, the service principal contains two objects in the keyCredentials collection: one for the private key and one for the public key; and an object in the passwordCredentials collection for the certificate password.
Option 1: Create a token signing certificate for the service principal
POST https://graph.microsoft.com/v1.0/servicePrincipals/d3616293-fff8-4415-9f01-33b05dad1b46/addTokenSigningCertificate
Content-type: application/json
{
"displayName": "CN=AWSContoso",
"endDateTime": "2027-01-22T00:00:00Z"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.ServicePrincipals.Item.AddTokenSigningCertificate;
var requestBody = new AddTokenSigningCertificatePostRequestBody
{
DisplayName = "CN=AWSContoso",
EndDateTime = DateTimeOffset.Parse("2027-01-22T00:00:00Z"),
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals["{servicePrincipal-id}"].AddTokenSigningCertificate.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
"time"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphserviceprincipals "github.com/microsoftgraph/msgraph-sdk-go/serviceprincipals"
//other-imports
)
requestBody := graphserviceprincipals.NewAddTokenSigningCertificatePostRequestBody()
displayName := "CN=AWSContoso"
requestBody.SetDisplayName(&displayName)
endDateTime , err := time.Parse(time.RFC3339, "2027-01-22T00:00:00Z")
requestBody.SetEndDateTime(&endDateTime)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
addTokenSigningCertificate, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").AddTokenSigningCertificate().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.serviceprincipals.item.addtokensigningcertificate.AddTokenSigningCertificatePostRequestBody addTokenSigningCertificatePostRequestBody = new com.microsoft.graph.serviceprincipals.item.addtokensigningcertificate.AddTokenSigningCertificatePostRequestBody();
addTokenSigningCertificatePostRequestBody.setDisplayName("CN=AWSContoso");
OffsetDateTime endDateTime = OffsetDateTime.parse("2027-01-22T00:00:00Z");
addTokenSigningCertificatePostRequestBody.setEndDateTime(endDateTime);
SelfSignedCertificate result = graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").addTokenSigningCertificate().post(addTokenSigningCertificatePostRequestBody);
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\ServicePrincipals\Item\AddTokenSigningCertificate\AddTokenSigningCertificatePostRequestBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new AddTokenSigningCertificatePostRequestBody();
$requestBody->setDisplayName('CN=AWSContoso');
$requestBody->setEndDateTime(new \DateTime('2027-01-22T00:00:00Z'));
$result = $graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->addTokenSigningCertificate()->post($requestBody)->wait();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.serviceprincipals.item.add_token_signing_certificate.add_token_signing_certificate_post_request_body import AddTokenSigningCertificatePostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = AddTokenSigningCertificatePostRequestBody(
display_name = "CN=AWSContoso",
end_date_time = "2027-01-22T00:00:00Z",
)
result = await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').add_token_signing_certificate.post(request_body)
You can use the following PowerShell and C# scripts to get a self-signed certificate for testing. Use your company's best security practices to create a signing certificate for production.
The following script creates a self-signed certificate with the name you give in fqdn when prompted, for example, CN=AWSContoso. It protects the certificate with the password you supply in pwd and exports the PFX and CER certificates to the location you specify in location.
The following C# console app can be used as a proof of concept to understand how the required values can be obtained. This code is for learning and reference only and shouldn't be used as-is in production.
using System;
using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates;
using System.Text;
/* CONSOLE APP - PROOF OF CONCEPT CODE ONLY!!
* This code uses a self signed certificate and should not be used
* in production. This code is for reference and learning ONLY.
*/
namespace Self_signed_cert
{
class Program
{
static void Main(string[] args)
{
// Generate a guid to use as a password and then create the cert.
string password = Guid.NewGuid().ToString();
var selfsignedCert = buildSelfSignedServerCertificate(password);
// Print values so we can copy paste into the JSON fields.
// Print out the private key in base64 format.
Console.WriteLine("Private Key: {0}{1}", Convert.ToBase64String(selfsignedCert.Export(X509ContentType.Pfx, password)), Environment.NewLine);
// Print out the start date in ISO 8601 format.
DateTime startDate = DateTime.Parse(selfsignedCert.GetEffectiveDateString()).ToUniversalTime();
Console.WriteLine("For All startDateTime: " + startDate.ToString("o"));
// Print out the end date in ISO 8601 format.
DateTime endDate = DateTime.Parse(selfsignedCert.GetExpirationDateString()).ToUniversalTime();
Console.WriteLine("For All endDateTime: " + endDate.ToString("o"));
// Print the GUID used for keyId
string signAndPasswordGuid = Guid.NewGuid().ToString();
string verifyGuid = Guid.NewGuid().ToString();
Console.WriteLine("GUID to use for keyId for keyCredentials->Usage == Sign and passwordCredentials: " + signAndPasswordGuid);
Console.WriteLine("GUID to use for keyId for keyCredentials->Usage == Verify: " + verifyGuid);
// Print out the password.
Console.WriteLine("Password is: {0}", password);
// Print out a displayName to use as an example.
Console.WriteLine("displayName to use: CN=Example");
Console.WriteLine();
// Print out the public key.
Console.WriteLine("Public Key: {0}{1}", Convert.ToBase64String(selfsignedCert.Export(X509ContentType.Cert)), Environment.NewLine);
Console.WriteLine();
// Generate the customKeyIdentifier using hash of thumbprint.
Console.WriteLine("You can generate the customKeyIdentifier by getting the SHA256 hash of the certs thumprint.\nThe certs thumbprint is: {0}{1}", selfsignedCert.Thumbprint, Environment.NewLine);
Console.WriteLine("The hash of the thumbprint that we will use for customeKeyIdentifier is:");
string keyIdentifier = GetSha256FromThumbprint(selfsignedCert.Thumbprint);
Console.WriteLine(keyIdentifier);
}
// Generate a self-signed certificate.
private static X509Certificate2 buildSelfSignedServerCertificate(string password)
{
const string CertificateName = @"Microsoft Azure Federated SSO Certificate TEST";
DateTime certificateStartDate = DateTime.UtcNow;
DateTime certificateEndDate = certificateStartDate.AddYears(2).ToUniversalTime();
X500DistinguishedName distinguishedName = new X500DistinguishedName($"CN={CertificateName}");
using (RSA rsa = RSA.Create(2048))
{
var request = new CertificateRequest(distinguishedName, rsa, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);
request.CertificateExtensions.Add(
new X509KeyUsageExtension(X509KeyUsageFlags.DataEncipherment | X509KeyUsageFlags.KeyEncipherment | X509KeyUsageFlags.DigitalSignature, false));
var certificate = request.CreateSelfSigned(new DateTimeOffset(certificateStartDate), new DateTimeOffset(certificateEndDate));
certificate.FriendlyName = CertificateName;
return new X509Certificate2(certificate.Export(X509ContentType.Pfx, password), password, X509KeyStorageFlags.Exportable);
}
}
// Generate hash from thumbprint.
public static string GetSha256FromThumbprint(string thumbprint)
{
var message = Encoding.ASCII.GetBytes(thumbprint);
SHA256Managed hashString = new SHA256Managed();
return Convert.ToBase64String(hashString.ComputeHash(message));
}
}
}
Extract certificate details
From the previous step, you have the CER and PFX certificates. Extract the values for the private key, password, public key, and the certificate thumbprint to add to the service principal.
Extract the certificate thumbprint
Request
The following PowerShell script allows you to extract the thumbprint from the CER file. Replace the file path with the location of your certificate.
## Replace the file path with the source of your certificate
Get-PfxCertificate -Filepath "C:\Users\admin\Desktop\CN=AWSContoso.cer" | Out-File -FilePath "C:\Users\admin\Desktop\CN=AWSContoso.cer.thumbprint.txt"
Response
The CN=AWSContoso.cer.thumbprint.txt file has an entry similar to the following output.
Add the following details to the keyCredentials and passwordCredentials for the service principal. Where the two objects have the same properties, you must assign the same values for those properties.
The customKeyIdentifier is the certificate thumbprint hash.
The startDateTime is the date when or after the certificate was created.
The endDateTime can be a maximum of three years from the startDateTime. If unspecified, the system automatically assigns a date one year after the startDateTime.
The type and usage must be:
AsymmetricX509Cert and Verify respectively in the same object.
X509CertAndPassword and Sign respectively in the same object.
Assign the certificate subject name to the displayName property.
The key is the Base64 encoded value that you generated in the previous step.
The keyId is a GUID that you can define.
The request returns a 204 No Content response code.
You need to set the preferredTokenSigningKeyThumbprint property of the service principal to the thumbprint of the certificate that you want Microsoft Entra ID to use to sign the SAML response. The request returns a 204 No Content response code.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new ServicePrincipal
{
PreferredTokenSigningKeyThumbprint = "5214D6BA9438F984A0CC2C856CCEA6A76EDCEC3A",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals["{servicePrincipal-id}"].PatchAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewServicePrincipal()
preferredTokenSigningKeyThumbprint := "5214D6BA9438F984A0CC2C856CCEA6A76EDCEC3A"
requestBody.SetPreferredTokenSigningKeyThumbprint(&preferredTokenSigningKeyThumbprint)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
servicePrincipals, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Patch(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ServicePrincipal servicePrincipal = new ServicePrincipal();
servicePrincipal.setPreferredTokenSigningKeyThumbprint("5214D6BA9438F984A0CC2C856CCEA6A76EDCEC3A");
ServicePrincipal result = graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").patch(servicePrincipal);
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ServicePrincipal;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ServicePrincipal();
$requestBody->setPreferredTokenSigningKeyThumbprint('5214D6BA9438F984A0CC2C856CCEA6A76EDCEC3A');
$result = $graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->patch($requestBody)->wait();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ServicePrincipal(
preferred_token_signing_key_thumbprint = "5214D6BA9438F984A0CC2C856CCEA6A76EDCEC3A",
)
result = await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').patch(request_body)
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new AppRoleAssignment
{
PrincipalId = Guid.Parse("59bb3898-0621-4414-ac61-74f9d7201355"),
PrincipalType = "User",
AppRoleId = Guid.Parse("3a84e31e-bffa-470f-b9e6-754a61e4dc63"),
ResourceId = Guid.Parse("d3616293-fff8-4415-9f01-33b05dad1b46"),
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals["{servicePrincipal-id}"].AppRoleAssignments.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
"github.com/google/uuid"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewAppRoleAssignment()
principalId := uuid.MustParse("59bb3898-0621-4414-ac61-74f9d7201355")
requestBody.SetPrincipalId(&principalId)
principalType := "User"
requestBody.SetPrincipalType(&principalType)
appRoleId := uuid.MustParse("3a84e31e-bffa-470f-b9e6-754a61e4dc63")
requestBody.SetAppRoleId(&appRoleId)
resourceId := uuid.MustParse("d3616293-fff8-4415-9f01-33b05dad1b46")
requestBody.SetResourceId(&resourceId)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
appRoleAssignments, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").AppRoleAssignments().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
AppRoleAssignment appRoleAssignment = new AppRoleAssignment();
appRoleAssignment.setPrincipalId(UUID.fromString("59bb3898-0621-4414-ac61-74f9d7201355"));
appRoleAssignment.setPrincipalType("User");
appRoleAssignment.setAppRoleId(UUID.fromString("3a84e31e-bffa-470f-b9e6-754a61e4dc63"));
appRoleAssignment.setResourceId(UUID.fromString("d3616293-fff8-4415-9f01-33b05dad1b46"));
AppRoleAssignment result = graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").appRoleAssignments().post(appRoleAssignment);
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.app_role_assignment import AppRoleAssignment
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = AppRoleAssignment(
principal_id = UUID("59bb3898-0621-4414-ac61-74f9d7201355"),
principal_type = "User",
app_role_id = UUID("3a84e31e-bffa-470f-b9e6-754a61e4dc63"),
resource_id = UUID("d3616293-fff8-4415-9f01-33b05dad1b46"),
)
result = await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').app_role_assignments.post(request_body)
Step 8: Get Microsoft Entra ID SAML metadata for AWS Contoso app
Use the following URL to get the Microsoft Entra ID SAML metadata for AWS Contoso app. Replace {tenant-id} with the tenant ID and {appId} with the appId of the AWS Contoso app. The metadata contains information such as the signing certificate, Microsoft Entra entityID, and Microsoft Entra SingleSignOnService, among others.
Now that you've completed the configuration steps for the application in Microsoft Entra ID and have the SAML metadata, sign in to your AWS IAM Identity Center company site as an administrator and:
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Applications["{application-id}"].DeleteAsync();
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
//other-imports
)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Applications().ByApplicationId("application-id").Delete(context.Background(), nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
graphClient.applications().byApplicationId("{application-id}").delete();
<?php
use Microsoft\Graph\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$graphServiceClient->applications()->byApplicationId('application-id')->delete()->wait();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
await graph_client.applications.by_application_id('application-id').delete()
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Users["{user-id}"].DeleteAsync();
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
//other-imports
)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Users().ByUserId("user-id").Delete(context.Background(), nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
graphClient.users().byUserId("{user-id}").delete();
<?php
use Microsoft\Graph\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$graphServiceClient->users()->byUserId('user-id')->delete()->wait();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
await graph_client.users.by_user_id('user-id').delete()
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Policies.ClaimsMappingPolicies["{claimsMappingPolicy-id}"].DeleteAsync();
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
//other-imports
)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Policies().ClaimsMappingPolicies().ByClaimsMappingPolicyId("claimsMappingPolicy-id").Delete(context.Background(), nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
graphClient.policies().claimsMappingPolicies().byClaimsMappingPolicyId("{claimsMappingPolicy-id}").delete();
<?php
use Microsoft\Graph\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$graphServiceClient->policies()->claimsMappingPolicies()->byClaimsMappingPolicyId('claimsMappingPolicy-id')->delete()->wait();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
await graph_client.policies.claims_mapping_policies.by_claims_mapping_policy_id('claimsMappingPolicy-id').delete()