Aids in the development and deployment of the Azure B2C Identity Experience Policy (IEF) xml files. Provides cmdlets to initiate a new policy set from the starter packs, add OIDC and SAML IdP technical profiles and journey updates, add SAML RPs, merge community and other samples into the set, perform static code analysis and deploy to B2C with no need for deployment-specific source changes. Also, includes commands for downloading existing policy sets or deleting them from a B2C tenant. Includes a command that may be used to setup a new B2C tenant for use with IEF. Makes it easy to re-deploy the same set of xml policies to multiple tenants (dev, test, etc.) by just adjusting the configuration file used by the import cmdlet. Supports either interactive or un-attended (client credentials) authentication to a B2C tenant.
This repo shows how to use this module in an Azure Pipeline for continous deployment of custom journeys.
This module can be installed from the PowerShell Gallery
| Name | Description |
|---|---|
| 3.1.20 | Added option to include HRD-related artifacts in AAD MT, SAML and OIDCV IdP definitions; using tolower for domain name; added configurationFilePath to add IdP |
| 3.1.19 | Fixed: invalid redirectUri was generated if mix-case characters were used in b2C name in connect-iefpolicies |
| 3.1.16 | Added ConvertTo-IEFPolicies cmdlet |
| 3.1.15 | Debug-IefPolicies checks for IncludeClaimResolvingInClaimsHandling |
| New-iefPolicies creates B2C tenant-specific conf file if user is signed in | |
| Minor bug fixes | |
| 3.1.14 | Base.xml marked as read-only in New-IefPols |
| 3.1.13 | Added support for some new idP types (Amazon, Git, etc.) |
| Bug fix: handling of tenants with multiple custom domains | |
| 3.1.12 | Added DisplayControls flag to New-IefPolicies; AAD returns email claim |
| 3.1.11 | Improved Debug- cmd, bug fixes for AddIdP |
| 3.1.9 | Minor mods: display SAML metadata url for new IdP, fix bug when running on Mac |
| 3.1.7 | Fixes: SAML RP created wrong policy key; AAD MT failed at runtime |
| 3.1.5 | New: noPrefix flag in Import-IefPolicies |
| 3.1.4 | New: list policy structure as part of Debug-IefPolicies output |
| Fix: reverted back to specifying all needed permissions instead of AccessAsUser | |
| Change: Add-IefPoliciesIdp -protocol aad adds AAD MT support to a policy set | |
| 3.1.3 | New: Debug-IefPolicies |
| 3.1.2 | New: New-IefPoliciesSamlRP |
| 3.1.0 | Change: import adds AAD-Common extensions app TP to Extensions.xml |
| 3.0.6 | Change: import all policies if conf file changed since last upload |
| New: Add-IefPoliciesIdP adds a SAMl or OIDC IdP to an existing policy set and updates journey definitions with the new exchange | |
| Update: Import-IefPolicies will replace {ExtAppId} and {ExtObjectId} strings with the correct B2C extensions app values | |
| 3.0.5 | Update: Export-IefPolicies -clean option modifies downloaded files to startpack-like content |
| 3.0.3 | Update: Import-IefPolicies will first look for .\yourtenantname.json before .\conf.json |
| 3.0.2 | Update: New-iefPoliciesKey allows providing a value |
| New: New function: New-IefPoliciesCert | |
| 3.0.0 | New: Requires PS 7.x. |
| 2.2.11 | New: Initialize-IefPolicies and Get-IefPoliciesAADCommon |
| 2.2.10 | New: use values from secrets.json in same directory as conf file |
| 2.2.9 | New: Include sample conf.json in the Add-IefPoliciesSample operation |
| 2.2.8 | New: Remove-IefPolicies |
| Improved: exception handling and error reporting | |
| 2.2.7 | Modified: check conf.json validity to avoid null prefix setting |
| 2.2.6 | Fixed: breaking change in MS Graph no longer returning tenantid in @odata.id |
| 2.2.4 | Added support for using {tenantId} as automatic replacement property ({Policy:TrustFrameworkTenantId} defined in IEF cannot be used in some policy properties) |
Note: these commands may be in a stand-alone PowerShell console (must be ver 7 or higher) or from VSCode Terminal (PowerShell) console. Note: all examples below assume that the PowerShell console is positioned on a working directory (here demo) where xml policies are or are to be stored.
If your B2C is not yet setup for using IEF as per instructions provided in the official documentation execute:
Connect-IefPolicies myb2ctenant
Initialize-IefPoliciesor use use the IEF setup website.
PS C:\demo> New-IefPolicies
Package type:
\[L\]ocal accounts only,
\[S\] Social/federated only,
\[SL\]ocal and social/federated,
\[M\]FA social/federated and local with MFA?
\[Q\]uit: SL
PS C:\demo> connect-iefpolicies myb2ctenant
PS C:\demo> import-iefpoliciesPS C:\demo> New-IefPolicies
Package type:
\[L\]ocal accounts only,
\[S\] Social/federated only,
\[SL\]ocal and social/federated,
\[M\]FA social/federated and local with MFA?
\[Q\]uit: SL
PS C:\demo> connect-iefpolicies myb2ctenant
PS C:\demo> Add-IefPoliciesIdP SAML -name Contoso
PS C:\demo> copy ./federation .
PS C:\demo> import-iefpoliciesPS C:\demo> New-IefPolicies
Package type:
\[L\]ocal accounts only,
\[S\] Social/federated only,
\[SL\]ocal and social/federated,
\[M\]FA social/federated and local with MFA?
\[Q\]uit: SL
PS C:\demo> connect-iefpolicies myb2ctenant
PS C:\demo> New-IefPoliciesSamlRP -issuerName Contoso
PS C:\demo> copy ./federation .
PS C:\demo> import-iefpoliciesDebug-IefPoliciesThe following script will deploy a new SocialAndLocalWithMFA starter pack, augmented with a journey supporting sign in/up, profile edit and password reset in one RelyingParty. The uploaded policies will be named B2C_1A_V1_ unless the V1_ string is changed in the associated conf.json file.
cd 'c:\some empty directory'
New-IefPolicies
*select M when prompted*
Add-IefPoliciesSample AllInOne -owner mrochon -repo b2csamples
Connect-IefPolicies yourb2c
Import-IefPolicies- Add-IEFPoliciesSample
- Add-IEFPoliciesIdP
- Connect-IEFPolicies
- ConvertTo-IEFPolicies
- Debug-IEFPolicies
- Export-IEFPolicies
- Get-IEFPoliciesAADCommon
- Import-IEFPolicies
- Initialize-IEFPolicies
- New-IEFPolicies
- New-IEFPoliciesCert
- New-IEFPoliciesKey
- New-IEFPoliciessamlRP
- Remove-IEFPolicies
Downloads policy files from one of the B2C Community samples. Only xml policy files are downloaded. Since these do not include the base xml file, and individual files are named uniquely to the sample type, you can usually add them to an existing startr pack set. You should check which starter pack they are based on.
The following example add a single policy from a specific B2C Community to the current folder.
cd 'c:\your directory with the IEF policies'
Add-IEFPoliciesSample default-home-realm-discovery
Add-IefPoliciesSample ConditionalAccess -owner mrochon -repo b2csamplesParameters:
| Property name | Required | Purpose |
|---|---|---|
| sampleName | Y | Name of the sub-folder within the policies folder which contains the sample |
| destinationPath | N | Directory to download the files to. Current directory by default. |
| owner | N | Git repo owner (default: Azure-ad-b2) |
| repository | N | Repo name (default: samples). IEF policies must be in a policies folder |
Adds a standard SAML, OIDC IdP or one of the social IdPs (Amazon, eBay, etc.) to an existing policy set and updates journeys to usereference it. The new policy xml files are created in a separate folder. You can then relace the existing policy files with the new ones.
As part of the process, this command adds a new object to the configuration file with data that needs to be provided before the policies are imported
Add-IefPolicies -protocol AAD and Add-IefPolicies -protocol MSA adds AAD multi-tenant and Microsoft Account (MSA) support to the policy set with no further need to complete the configuration in an AAD tenant. If not already in existence, this command will register the appropriate applications and secrets in the current B2C tenant.
The following command will add a new OIDC TechnicalProfile named Contoso-OIDC to the TrustFrameworkExtension.xml and add references to it to all journeys referenced by relying parties defined in this policy set. It will also extend the conf.json file with some additional settings (e.g. metadata url) to be used when importing these files to B2C.
cd 'c:\your directory with the IEF policies'
Add-IEFPoliciesIdP OIDC -Name ContosoParameters:
| Property name | Required | Purpose |
|---|---|---|
| protocol | N | IdP type name: OIDC (default), AAD (multi-tenant), SAML, ADFS, Amazon, eBay, Git, Google, LinkedIn, MSA, Ping, Twitter |
| Name | Y | Issuer name |
| sourceDirectoryPath | N | Current policies source xml files |
| updatedSourceDirectory | N | Directory where any new/updated files will be stored (default: ./federations) |
| fedeationsPolicyFile | N | File name (may not exist) where new technical profile will be added (default: TrustFrameworkExtensions.xml) |
| configurationFilePath | N | Variable configuration data file (default: ./conf.json) |
| withHRD | N | Boolean, if $true IdP TechnicalProfiles for AAD MT, SAML and OIDC will include HRD support (using ClaimTypeOnWhichToEnable) |
Use Connect-IEFPolicies cmdlet to sign in to your B2C tenant and obtain access tokens needed to execute other cmdlets (import- and export-) in this module which require Graph access to the tenant. You can sign in either interactively using user credentials or using application credentials (id and secret). For the former, the user must be have a directory role with sufficient privileges to execute requested actions.
To use the OAuth2 Client Credentials tokens, using application id and secret, register the application for use with Microsoft Graph and grant it the following application permissions:
- Application.Read.All
- Domain.Read.All
- Organization.Read.All
- Policy.ReadWrite.TrustFramework
- TrustFrameworkKeySet.ReadWrite.All (if module used to create policy keys or initialize the tenant)
For interactive signin you do not need to register the application. This module is already registered as an AAD multi-tenant app.
E.g.
Connect-IefPolicies -tenant myTenant
Connect-IefPolicies -tenant myTenant -clientId "registered app id" -clientSecret "secret"| Property name | Required | Purpose |
|---|---|---|
| tenant | N | Name of tenant you want to sign into. '.onmicrosoft.com' is not required. This parameter is required if you are signing in with an account which is an invited guest in your B2C tenant |
| clientId | N | id of an application registered in your tenant for non-interactive signin |
| clientSecret | N | Secret generated for the app |
Creates configuration json file(s) for use in Import-IEFPolicies from the json settings file used by VSCode B2C Extension. Import-IEFPolicies uses one json setting file per B2C tenant to which IEF policies are loaded. Each such file is named with the B2C tenant's name, e.g. myb2c.json would be used when importing policies into myb2c.onmicrosoft.com tenant. Also, since Import-IEFPolicies automatically replaces certain fixed strings, e.g. yourtenant with values based on the tenant to which the policies are being imported, this command drops these values (tenant name, IEF application ids) from the configuration files and provides instructions on how to adapt the xml accordingly.
Note: Import-IEFPolicies will also replace any instances of '{ExtAppId}" and '{ExtObjectId}' with the appId and object id of the B2C extensions App found in the tenant into which the policies are being imported.
Convert-IefPolicies -extensionsFilePath ./appSettings.json -IefPoliciesDirectory ./newxml | Property name | Required | Purpose |
|---|---|---|
| extensionsFilePath | N | Path to the B2C Extensions settings file, default: './appSettings.json' |
| clienIefPoliciesDirectorytId | N | directory where new configuration files will be created, default: './' |
Debug-IEFPolicies performs static code analysis on a policy set, looking for common errors for which the policy load process does not provide any or adequate debugging information:
- Duplicate key names in a Metadata element (load reports that a duplicate key was found but does not specify where)
- Invalid claim names in Preconditions (these are not caught by the load process)
- Using claim names as the 2nd operand in a ClaimEquals condition in the mistaken expectation that values of claims will be compared. The comparison requires a literal value in that operand.
Debug-IefPolicies -sourceDirectoryPath 'c:\temp\ief'| Property name | Required | Purpose |
|---|---|---|
| sourceDirectoryPath | N | Directory path with policy set xml files (default: current working directory) |
Use Export-IEFPolicies function to download your IEF policies from the B2C tenant to a local folder.
E.g. download policies using V1 prefix ('B2C_1A_V1...') to current folder and remove tenant-specific identifiers (IEF App ids, etc.) from the xml.
cd C:\LocalAccounts\policies
Export-IEFPolicies V1 -clean `| Property name | Required | Purpose |
|---|---|---|
| prefix | Y | Download policies whose name starts with "B2C_1A_prefix" |
| destinationPath | N | Directory path where your xml policies are stored. Must already exist |
| clean | N | Modify xml to make it tenant independant, remove tenant-specific ids |
Note: when using the -clean option, this command will attempt to make the contents of the policy files tenant neutral, as similar to what you see in the B2C starter packs as possible. In particular, it will:
- replace all occurrences of the B2C tenant name (the first part of the abc.onmicrosoft.com) url with yourtenant literal
- replace all occurrences of the application ids of the IdentityExperienceFramework and ProxyIdentityExpereinceFramework with that name suffixed with AppId
- replace all occurences of the B2C extensions app app id and object id with {ExtAppId} and {ExtObjectId}
- create a conf.json file with the prefix setting
You should be able to connect-iefpolicies to a different B2C tenant and import-iefpolicies to that tenant with no further changes. If there are tenant-specific url REST function references or policy key container name referneces these will need to be changed manually before uploading.
This command is no longer needed: Import-IefPolicies will automatically replace references to {ExtAppId} and {ExtObjectId} with the tenant's 'b2c extensions app'
Displays application and object ids of a special B2C extensions application. These values are needed if your policies store or retrieve custom user attributes as for example in this sample
E.g.
Get-IefPoliciesAADCommonParameters: none
Use Import-IEFPolicies function to upload your IEF policies to the B2C tenant you are currently signed into.
Before uploading, the cmdlet will modify your xml files and store the new versions in the directory identified by the updatedSourceDirectory (.debug/ by default). The cmdlet will replace any occurrences of yourtenant string (used in all StarterPolicies) with the name of the tenant you have logged in using Connect-IefPolicies. It will use a json configuration file (if provided, by default it will look for conf.json in the current directory) to make other changes as well. The Json file defines values to be replaced in the original xml files. E.g.
{
"Prefix": "V1",
"MyRESTUrl": "https://mywebsite.com/users",
"Contoso": {
"ClientId": "123"
}
}will cause this cmdlet to:
- inject V1 into names of all policies, i.e. B2C_1A_TrustFrameworkBase will become B2C_1A_V1TrustFrameworkBase, etc.
- Replace occurrences of {ExtAppId} and {ExtObjectId} in xml the appId and objectId of the B2C extensions app in this B2C tenant
- Replace all occurrences of a string enclosed in curly braces, e.g. {MyRESTUrl} above, with the corresponding value (if present) in the .json file, e.g. above url (https://mywebsite.com/users).
- Replace occurrences of {Contoso:ClientId} with 123
If the same folder contains a secrets.json file, the attributes it defines will be added to those in the above configuration file. That allows you to configure your .gitignore file to not upload any confidential data (e.g. AppInsights key used for journey debugging) to your repos.
Connect-IefPolicies -Tenant yourtenant
cd 'c:\your directory with the IEF policies'
Import-IEFPolicies Parameters:
| Property name | Required | Purpose |
|---|---|---|
| sourceDirectory | N | Directory path where your xml policies are stored (default: current directory) |
| updatedSourceDirectory | N | Directory path where the policies updated by this script will be stored. Also used to prevent uploading unmodified policies. Default: ./debug/yourtenant subfolder. |
| configurationFilePath | N | json file with additional replacement strings. Default: .\b2cname>.json, otherwise .\conf.json. The script will match any property in this file with a string with format {} and replace it with the value of the property. See above about a secrets.json file |
| generateOnly | N | If used, the script will only generate policy files but not upload them to B2C |
| prefix | N | String inserted into the name of generated policies, e.g. the new base policy name will be *B2C_1A_XYZTrustFrameBase, where XYZ is the value of the provided prefix. Can also be set in the conf.json file |
| noprefix | N | Flag. When used, does not inject a prefix into thee policy names |
Performs B2C tenant setup as descibed in the official documentation. This setup is needed only once. This command will also add a fake Facebook policy key (B2C_1A_FacebookSecret) to allow uloading of policy sets with social provider support - they all use Facebook as example of a social provider.
Connect-IefPolicies <b2c name>
Initialize-IEFPoliciesNOTE: at completion this command displays a url which, when executed through a browser will allow an administrator to grant admin consent to one of the required applications (IEFProxy) have signin permissons to another. It is important to execute this consent as otherwise any uploaded policies will not work for local signin.
Parameters:
| Property name | Required | Purpose |
|---|---|---|
| validateOnly | N | Checks for presence of IEF-required applications |
Use New-IEFPolicies function to download a set of policies from the Azure B2C StarterPack. The cmdlet will prompt you for which of the starter packs (local, social, etc.) to download. A TechnicalProfile with references to teh b2C extension app (needed by persistent custom attributes) will be added to teh TrustFrameworkExtensions.xml.
E.g.
New-IefPolicies -destinationPath $dest | Property name | Required | Purpose |
|---|---|---|
| destinationPath | N | Directory path where your xml policies are stored. Will be created if does not already exist. Current directory is default |
| displayControls | N | Use the DisplayControls starter pack directory |
Creates and deploys into Policy Keys a new, self-signed signing certificate. A copy of the cert is stored locally in CurrentUser/My certificate storage.
E.g.
New-IEFPoliciesCert MyB2C `| Property name | Required | Purpose |
|---|---|---|
| keyName | Y | Policy key storage name. Used to create CName of the cert: keyName.b2cname.onmicrosoft.com |
| validityMonths | N | How long valid (default is 12 months) |
| startValidInMonths | N | How many months hence must the cert start being valid (default is 0 months) |
Creates a new key Policy Key secret.
E.g.
New-IefPoliciesKey AzureFuncKey -purpose sig -value "<Azure Function key value>" -validityInMonths 12| Property name | Required | Purpose |
|---|---|---|
| name | Y | key name |
| purpose | N | Purpose (default: sig; enc) |
| keyType | N | Key type (default: rsa; oct) |
| value | N | Secret, will be generated if not provided |
| startValidityInMonths | N | Valid from: number of months from now (default: 0) |
| validityInMonths | N | Validity period from valid from date (default: 12) |
Creates a new Saml Relying Party endpoint
E.g.
New-IefPoliciessamlRp| Property name | Required | Purpose |
|---|---|---|
| epName | N | Used to construct B2C signup/signin endpoint name: B2C_1A_[epName]_SUSI (default: SAML) |
| signingKeyName | N | Used to construct B2C issuing cert policy key container: B2C_1A_[epName]SigningKey (default: same as epName) |
| sourceDirectory | N | Policy set source (default: ./) |
| extensionFile | N | Policy file where to create the TechnicalProfile (default: TrustFrameworkExtensions,xml) |
| configurationFilePath | N | Path for conf.json file (default: ./conf.json) |
Delete a set of policies, whose name starts with the specified prefix from the tenant. User connfirmation will be requested before files are deleted.
For example, the following deletes all policies whose name starts with B2C_1A_V1.
Remove-IefPolicies V1| Property name | Required | Purpose |
|---|---|---|
| prefix | Y | Policy name prefix |