AdfsWebApiApplication - X-Guardian/AdfsDsc GitHub Wiki

AdfsWebApiApplication

Parameters

Parameter	Attribute	DataType	Description	Allowed Values
Name	Key	String	Specifies a name for the Web API application.
ApplicationGroup Identifier	Required	String	Specifies the ID of an application group for the Web API application.
Identifier	Required	StringArray[]	Specifies an identifier for the Web API application.
Description	Write	String	Specifies a description for the Web API application.
Ensure	Write	String	Specifies whether the Web API application should be present or absent. Default value is 'Present'.	`Present`, `Absent`
Allowed AuthenticationClass References	Write	StringArray[]	Specifies an array of allow authentication class references.
ClaimsProviderName	Write	StringArray[]	Specifies an array of claims provider names that you can configure for a relying party trust for Home Realm Discovery (HRD) scenario.
Issuance AuthorizationRules	Write	String	Specifies the issuance authorization rules.
Delegation AuthorizationRules	Write	String	Specifies delegation authorization rules.
Impersonation AuthorizationRules	Write	String	Specifies the impersonation authorization rules.
IssuanceTransform Rules	Write	MSFT_AdfsIssuanceTransformRule[]	Specifies the issuance transform rules.
Additional AuthenticationRules	Write	String	Specifies additional authentication rules.
AccessControlPolicy Name	Write	String	Specifies the name of an access control policy.
AccessControlPolicy Parameters	Write	MSFT_AdfsAccessControlPolicyParameters	Specifies the parameters and their values to pass to the Access Control Policy.
NotBeforeSkew	Write	SInt32	Specifies the not before skew value.
TokenLifetime	Write	SInt32	Specifies the token lifetime.
AlwaysRequire Authentication	Write	Boolean	Indicates that this Web API application role always requires authentication, even if it previously authenticated credentials for access. Specify this parameter to require users to always supply credentials to access sensitive resources.
AllowedClientTypes	Write	StringArray[]	Specifies allowed client types.	`None`, `Public`, `Confidential`
IssueOAuthRefresh TokensTo	Write	String	Specifies the refresh token issuance device types.	`NoDevice`, `WorkplaceJoinedDevices`, `AllDevices`
RefreshToken ProtectionEnabled	Write	Boolean	Indicates whether refresh token protection is enabled.
RequestMFAFromClaims Providers	Write	Boolean	Indicates that the request MFA from claims providers option is used.

MSFT_AdfsLdapMapping

Parameters

Parameter	Attribute	DataType	Description	Allowed Values
LdapAttribute	Required	String	Specifies the LDAP attribute.
OutgoingClaimType	Required	String	Specifies the outgoing claim type.

MSFT_AdfsIssuanceTransformRule

Parameters

Parameter	Attribute	DataType	Description	Allowed Values
TemplateName	Required	String	Specifies the name of the claim rule template	`LdapClaims`, `EmitGroupClaims`, `CustomClaims`
Name	Required	String	Specifies the name of the claim rule
AttributeStore	Write	String	Specifies the attribute store from which to extract LDAP attributes
LdapMapping	Write	MSFT_AdfsLdapMapping[]	Specifies the mapping pairs of LDAP attributes to outgoing claim types
GroupName	Write	String	Specifies the Active Directory group.
OutgoingClaimType	Write	String	Specifies the outgoing claim type.
OutgoingNameIDFormat	Write	String	Specifies the outgoing Name ID format if Name ID is specified as the outgoing claim type.
OutgoingClaimValue	Write	String	Specifies the outgoing claim value.
CustomRule	Write	String	Specifies the custom claim rule

MSFT_AdfsAccessControlPolicyParameters

Parameters

Parameter	Attribute	DataType	Description	Allowed Values
GroupParameter	Write	StringArray[]	Specifies the Group Parameter.

Description

The AdfsWebApiApplication DSC resource manages Web API Applications within Active Directory Federation Services. Web Api Applications are a construct that represents a web API secured by ADFS.

Requirements

Target machine must be running ADFS on Windows Server 2016 or above to use this resource.

Examples

Example 1

This configuration will add a Web API application to an application group in Active Directory Federation Services (AD FS).

Configuration AdfsWebApiApplication_Config
{
    param()

    Import-DscResource -ModuleName AdfsDsc

    Node localhost
    {
        AdfsApplicationGroup AppGroup1
        {
            Name        = 'AppGroup1'
            Description = "This is the AppGroup1 Description"
        }

        AdfsWebApiApplication WebApiApp1
        {
            Name                          = 'AppGroup1 - Web API'
            ApplicationGroupIdentifier    = 'AppGroup1'
            Identifier                    = 'e7bfb303-c5f6-4028-a360-b6293d41338c'
            Description                   = 'App1 Web Api'
            AccessControlPolicyName       = 'Permit everyone'
            AlwaysRequireAuthentication   = $false
            AllowedClientTypes            = 'Public', 'Confidential'
            IssueOAuthRefreshTokensTo     = 'AllDevices'
            NotBeforeSkew                 = 0
            RefreshTokenProtectionEnabled = $true
            RequestMFAFromClaimsProviders = $false
            TokenLifetime                 = 0
        }
    }
}

Example 2

This configuration will add a Web API application with an LDAP Claims issuance transform rule to an application group in Active Directory Federation Services (AD FS).

Configuration AdfsWebApiApplication_LdapClaims_IssuanceTransformRules_Config
{
    param()

    Import-DscResource -ModuleName AdfsDsc

    Node localhost
    {
        AdfsApplicationGroup AppGroup1
        {
            Name        = 'AppGroup1'
            Description = "This is the AppGroup1 Description"
        }

        AdfsWebApiApplication WebApiApp1
        {
            Name                          = 'AppGroup1 - Web API'
            ApplicationGroupIdentifier    = 'AppGroup1'
            Identifier                    = 'e7bfb303-c5f6-4028-a360-b6293d41338c'
            Description                   = 'App1 Web Api'
            AccessControlPolicyName       = 'Permit everyone'
            AlwaysRequireAuthentication   = $false
            AllowedClientTypes            = 'Public', 'Confidential'
            IssueOAuthRefreshTokensTo     = 'AllDevices'
            NotBeforeSkew                 = 0
            RefreshTokenProtectionEnabled = $true
            RequestMFAFromClaimsProviders = $false
            TokenLifetime                 = 0
            IssuanceTransformRules        = @(
                MSFT_AdfsIssuanceTransformRule
                {
                    TemplateName   = 'LdapClaims'
                    Name           = 'App1 Ldap Claims'
                    AttributeStore = 'Active Directory'
                    LdapMapping    = @(
                        MSFT_AdfsLdapMapping
                        {
                            LdapAttribute     = 'mail'
                            OutgoingClaimType = 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'
                        }
                        MSFT_AdfsLdapMapping
                        {
                            LdapAttribute     = 'sn'
                            OutgoingClaimType = 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname'
                        }
                    )
                }
            )
        }
    }
}

Example 3

This configuration will add a Web API application with an Emit Group Claims Issuance Transform rule to an application group in Active Directory Federation Services (AD FS).

Configuration AdfsWebApiApplication_EmitGroupClaims_IssuanceTransformRules_Config
{
    param()

    Import-DscResource -ModuleName AdfsDsc

    Node localhost
    {
        AdfsApplicationGroup AppGroup1
        {
            Name        = 'AppGroup1'
            Description = "This is the AppGroup1 Description"
        }

        AdfsWebApiApplication WebApiApp1
        {
            Name                          = 'AppGroup1 - Web API'
            ApplicationGroupIdentifier    = 'AppGroup1'
            Identifier                    = 'e7bfb303-c5f6-4028-a360-b6293d41338c'
            Description                   = 'App1 Web Api'
            AccessControlPolicyName       = 'Permit everyone'
            AlwaysRequireAuthentication   = $false
            AllowedClientTypes            = 'Public', 'Confidential'
            IssueOAuthRefreshTokensTo     = 'AllDevices'
            NotBeforeSkew                 = 0
            RefreshTokenProtectionEnabled = $true
            RequestMFAFromClaimsProviders = $false
            TokenLifetime                 = 0
            IssuanceTransformRules        = @(
                MSFT_AdfsIssuanceTransformRule
                {
                    TemplateName       = 'EmitGroupClaims'
                    Name               = 'App1 User Role Claim'
                    GroupName          = 'App1 Users'
                    OutgoingClaimType  = 'http://schemas.microsoft.com/ws/2008/06/identity/claims/role'
                    OutgoingClaimValue = 'User'
                }
            )
        }
    }
}

Example 4

This configuration will add a Web API application role with a Custom Claims Issuance Transform rule to an application group in Active Directory Federation Services (AD FS).

Configuration AdfsWebApiApplication_CustomClaims_IssuanceTransformRules_Config
{
    param()

    Import-DscResource -ModuleName AdfsDsc

    Node localhost
    {
        AdfsApplicationGroup AppGroup1
        {
            Name        = 'AppGroup1'
            Description = "This is the AppGroup1 Description"
        }

        AdfsWebApiApplication WebApiApp1
        {
            Name                          = 'AppGroup1 - Web API'
            ApplicationGroupIdentifier    = 'AppGroup1'
            Identifier                    = 'e7bfb303-c5f6-4028-a360-b6293d41338c'
            Description                   = 'App1 Web Api'
            AccessControlPolicyName       = 'Permit everyone'
            AlwaysRequireAuthentication   = $false
            AllowedClientTypes            = 'Public', 'Confidential'
            IssueOAuthRefreshTokensTo     = 'AllDevices'
            NotBeforeSkew                 = 0
            RefreshTokenProtectionEnabled = $true
            RequestMFAFromClaimsProviders = $false
            TokenLifetime                 = 0
            IssuanceTransformRules        = @(
                MSFT_AdfsIssuanceTransformRule
                {
                    TemplateName = 'CustomClaims'
                    Name         = 'App1 Custom Claim'
                    CustomRule   = 'c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"), query = ";givenName;{0}", param = c.Value);'
                }
            )
        }
    }
}

Example 5

This configuration will add a Web API application role with access control policy parameters to an application in Active Directory Federation Services (AD FS).

Configuration AdfsWebApiApplication_AccessControlPolicyParameters_Config
{
    param()

    Import-DscResource -ModuleName AdfsDsc

    Node localhost
    {
        AdfsApplicationGroup AppGroup1
        {
            Name        = 'AppGroup1'
            Description = "This is the AppGroup1 Description"
        }
        
        AdfsWebApiApplication WebApiApp1
        {
            Name                          = 'AppGroup1 - Web API'
            ApplicationGroupIdentifier    = 'AppGroup1'
            Identifier                    = 'e7bfb303-c5f6-4028-a360-b6293d41338c'
            Description                   = 'App1 Web Api'
            AccessControlPolicyName       = 'Permit specific group'
            AccessControlPolicyParameters = MSFT_AdfsAccessControlPolicyParameters
            {
                GroupParameter = @(
                    'CONTOSO\AppGroup1 Users'
                    'CONTOSO\AppGroup1 Admins'
                )
            }
        }
    }
}