SAML - Entra ID/Azure AD sample
The following is an example keycloak-saml.xml file for integrating Weave with Microsoft Entra ID (formerly Azure AD).
This example relies upon a new client being created in Entra ID specifically for Weave, and there are some values in this file that will need be replaced those from that Entra client. The SP entityID attribute (APPLICATION_ID_FROM_ENTRA in the example below) taken from the Application (client) ID and the Directory (tenant) ID (DIRECTORY_ID_FROM_ENTRA in the example below) for the various Entra URL endpoints.
Additionally Entra ID may need to be configured to return role or group information as described here:
https://docs.microsoft.com/en-us/azure/active-directory/hybrid/how-to-connect-fed-group-claims#add-group-claims-to-tokens-for-saml-applications-using-sso-configuration.
Entra may report the users groups using the groups object id, rather that it’s name, so to convert the object id’s back to their names you can either export the groups from Entra to a .csv file (the Entra console provides a button to do this, see below) and then reference that file in the xml config. Alternatively you can create your own properties file with a list object id to group mappings and reference that.
You do not need to do this but if you do no you will need to create ACL’s within Weave using the Object ID of the groups.
When creating the new client in Entra the redirect URL (back to Weave, see the last screen shot below) should be set to https://hostname.domainname/weave/saml (assuming the default application context is still /weave, and Weave is exposed on port 443 which it must be). If your Entra client configuration has multiple redirect URL’s, that is you’re trying to use the same Entra client definition for multiple Weave server instances, e.g. test and prod, then you may need to add an assertionConsumerServiceUrl attribute to the SingleSignOnService providing the full URL of Weave SAML endpoint, similar to the bindingUrl but pointing to Weave, not Microsoft. It will be one of the URL's you added to the Entra client configuration as the redirect URL, and if you do not set it Entra will always redirect back to the first redirect URL you specified.
Note, this example does not perform any verification of the information exchanged between the Entra IS identity provider and Weave, which is not recommended. You can find a more complete example that does use certificates at Keycloak - Securing Applications and Services Guide.
<keycloak-saml-adapter xmlns="urn:keycloak:saml:adapter"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:keycloak:saml:adapter https://www.keycloak.org/schema/keycloak_saml_adapter_1_10.xsd">
<SP entityID="spn:APPLICATION_ID_FROM_ENTRA"
sslPolicy="EXTERNAL"
nameIDPolicyFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
logoutPage="http://www.cohga.com/"
forceAuthentication="false"
isPassive="false"
turnOffChangeSessionIdOnLogin="false"
autodetectBearerOnly="true">
<!-- This sets up the attribute returned by Entra ID to use as the username -->
<PrincipalNameMapping policy="FROM_ATTRIBUTE" attribute="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" />
<!-- This sets up the attribute returned by Entra ID to determine the roles the user has -->
<!-- these roles shoud be referenced in your Weave ACL configurations -->
<RoleIdentifiers>
<Attribute name="http://schemas.microsoft.com/ws/2008/06/identity/claims/group"/>
<!-- These two are alternate names in case the one above does not work
<Attribute name="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"/>
<Attribute name="http://schemas.microsoft.com/ws/2008/06/identity/claims/role"/>
<Attribute name="http://schemas.xmlsoap.org/claims/Group"/>
-->
</RoleIdentifiers>
<!-- Convert Entra group id's to their display name via an Entra group export csv file -->
<!-- Note the id is correct, it contains azure and has not as yet been renamed -->
<RoleMappingsProvider id="azure-groups-role-mapper">
<Property name="export.file.location" value="platform/workspace/exportGroup_2022-8-17.csv"/>
</RoleMappingsProvider>
<!-- Or, convert Entra group id's to their display name via a properties file -->
<!--
<RoleMappingsProvider id="properties-based-role-mapper">
<Property name="properties.file.location" value="platform/workspace/group-mappings.properties"/>
</RoleMappingsProvider>
-->
<IDP entityID="idp"
signaturesRequired="false">
<SingleSignOnService requestBinding="POST"
bindingUrl="https://login.microsoftonline.com/DIRECTORY_ID_FROM_ENTRA/saml2"
signRequest="false"
validateAssertionSignature="false"
validateResponseSignature="false"/>
<SingleLogoutService
requestBinding="POST"
responseBinding="POST"
postBindingUrl="https://login.microsoftonline.com/DIRECTORY_ID_FROM_ENTRA/saml2"
redirectBindingUrl="https://login.microsoftonline.com/DIRECTORY_ID_FROM_ENTRA/saml2"
signRequest="false"
signResponse="false"/>
</IDP>
</SP>
</keycloak-saml-adapter>
