Merge branch 'main' of https://github.com/MicrosoftDocs/azure-docs-pr into cold-tier

Author: normesta

articles/active-directory/authentication/concept-system-preferred-multifactor-authentication.md

@@ -14,6 +14,7 @@ ms.collection: M365-identity-device-management
 
 # Customer intent: As an identity administrator, I want to encourage users to use the Microsoft Authenticator app in Azure AD to improve and secure user sign-in events.
 ---
+
 # System-preferred multifactor authentication  - Authentication methods policy
 
 System-preferred multifactor authentication (MFA) prompts users to sign in by using the most secure method they registered. Administrators can enable system-preferred MFA to improve sign-in security and discourage less secure sign-in methods like SMS.
@@ -111,7 +112,7 @@ When a user signs in, the authentication process checks which authentication met
 
 1. [Temporary Access Pass](howto-authentication-temporary-access-pass.md)
 1. [FIDO2 security key](concept-authentication-passwordless.md#fido2-security-keys)
-1. [Microsoft Authenticator push notifications](concept-authentication-authenticator-app.md)
+1. [Microsoft Authenticator notifications](concept-authentication-authenticator-app.md)
 1. [Time-based one-time password (TOTP)](concept-authentication-oath-tokens.md)<sup>1</sup>
 1. [Telephony](concept-authentication-phone-options.md)<sup>2</sup>
 1. [Certificate-based authentication](concept-certificate-based-authentication.md)
@@ -134,3 +135,5 @@ The system-preferred MFA also applies for users who are enabled for MFA in the l
 
 * [Authentication methods in Azure Active Directory](concept-authentication-authenticator-app.md)
 * [How to run a registration campaign to set up Microsoft Authenticator](how-to-mfa-registration-campaign.md)
+
+

articles/active-directory/cloud-infrastructure-entitlement-management/TOC.yml

@@ -27,6 +27,8 @@
         href: onboard-enable-controller-after-onboarding.md
       - name: Add an account/ subscription/ project after onboarding is complete
         href: onboard-add-account-after-onboarding.md
+      - name: Create folders to organize your Authorization Systems
+        href: how-to-create-folders.md
     - name: View information about your Authorization Systems
       expanded: false
       items:

articles/active-directory/cloud-infrastructure-entitlement-management/how-to-create-folders.md

@@ -0,0 +1,32 @@
+---
+title: Create folders to organize your Authorization Systems
+description: How to create folders to organize Authorization Systems - accounts, subscriptions, and projects - in Microsoft Entra Permissions Management.
+services: active-directory
+author: jenniferf-skc
+manager: amycolannino
+ms.service: active-directory 
+ms.subservice: ciem
+ms.workload: identity
+ms.topic: how-to
+ms.date: 08/09/2023
+ms.author: jfields
+---
+
+# Create folders to organize your authorization systems
+
+After onboarding your cloud environment to Permissions Management, you might have multiple authorization systems (AWS accounts, Azure subscriptions, or GCP projets) that you need to manage. You can create folders to organize and group together your list of accounts, subscriptions, or projects to manage your workflow more efficiently. 
+
+## Create a folder
+
+1. On the Permissions Management home page, select the **Data Collectors** tab and make sure that the **Status** for your cloud environment is **Onboarded**.
+1. Select the **Authorization Systems** subtab, then **Folders**.
+1. Click **Create Folder**.
+1. In the **Folder Name** field, enter a name for the folder you want to create.
+1. From the list of names, select all Authorization Systems (accounts, subscriptions, or projects) you want to add to this folder.
+1. Click **Save**. Your folder is created. 
+1. Repeat these steps to create as many folders as you need. 
+
+## Next steps
+
+- [View key statistics and data about your authorization systems](ui-dashboard.md)
+- [View data about the activity in your authorization system](product-dashboard.md)

articles/active-directory/develop/jwt-claims-customization.md

@@ -195,6 +195,288 @@ As another example, consider when Britta Simon tries to sign in using the follow
 
 As a final example, consider what happens if Britta has no `user.othermail` configured or it's empty. The claim falls back to `user.extensionattribute1` ignoring the condition entry in both cases.
 
+## Security considerations
+Applications that receive tokens rely on claim values that are authoritatively issued by Azure AD and can't be tampered with. When you modify the token contents through claims customization, these assumptions may no longer be correct. Applications must explicitly acknowledge that tokens have been modified by the creator of the customization to protect themselves from customizations created by malicious actors. This can be done in one the following ways:
+
+- [Configure a custom signing key](#configure-a-custom-signing-key)
+- [update the application manifest to accept mapped claims](#update-the-application-manifest).  
+
+Without this, Azure AD returns an [AADSTS50146 error code](reference-aadsts-error-codes.md#aadsts-error-codes).
+
+## Configure a custom signing key
+For multi-tenant apps, a custom signing key should be used. Don't set `acceptMappedClaims` in the app manifest. when setting up an app in the Azure portal, you get an app registration object and a service principal in your tenant. That app is using the Azure global sign-in key, which can't be used for customizing claims in tokens. To get custom claims in tokens, create a custom sign-in key from a certificate and add it to service principal. For testing purposes, you can use a self-signed certificate. After configuring the custom signing key, your application code needs to validate the token signing key.
+
+Add the following information to the service principal:
+
+- Private key (as a [key credential](/graph/api/resources/keycredential?view=graph-rest-1.0&preserve-view=true))
+- Password (as a [password credential](/graph/api/resources/passwordcredential?view=graph-rest-1.0&preserve-view=true))
+- Public key (as a [key credential](/graph/api/resources/keycredential?view=graph-rest-1.0&preserve-view=true))
+
+Extract the private and public key base-64 encoded from the PFX file export of your certificate. Make sure that the `keyId` for the `keyCredential` used for "Sign" matches the `keyId` of the `passwordCredential`. You can generate the `customkeyIdentifier` by getting the hash of the cert's thumbprint.
+
+## Request
+The following example shows the format of the HTTP PATCH request to add a custom signing key to a service principal. The "key" value in the `keyCredentials` property is shortened for readability. The value is base-64 encoded. For the private key, the property usage is "Sign". For the public key, the property usage is "Verify".
+
+```
+PATCH https://graph.microsoft.com/v1.0/servicePrincipals/f47a6776-bca7-4f2e-bc6c-eec59d058e3e
+
+Content-type: servicePrincipals/json
+Authorization: Bearer {token}
+
+{
+    "keyCredentials":[
+        {
+            "customKeyIdentifier": "lY85bR8r6yWTW6jnciNEONwlVhDyiQjdVLgPDnkI5mA=", 
+            "endDateTime": "2021-04-22T22:10:13Z",
+            "keyId": "4c266507-3e74-4b91-aeba-18a25b450f6e",
+            "startDateTime": "2020-04-22T21:50:13Z",
+            "type": "X509CertAndPassword",
+            "usage": "Sign",
+            "key":"MIIKIAIBAz.....HBgUrDgMCERE20nuTptI9MEFCh2Ih2jaaLZBZGeZBRFVNXeZmAAgIH0A==",
+            "displayName": "CN=contoso"
+        },
+        {
+            "customKeyIdentifier": "lY85bR8r6yWTW6jnciNEONwlVhDyiQjdVLgPDnkI5mA=",
+            "endDateTime": "2021-04-22T22:10:13Z",
+            "keyId": "e35a7d11-fef0-49ad-9f3e-aacbe0a42c42",
+            "startDateTime": "2020-04-22T21:50:13Z",
+            "type": "AsymmetricX509Cert",
+            "usage": "Verify",
+            "key": "MIIDJzCCAg+gAw......CTxQvJ/zN3bafeesMSueR83hlCSyg==",
+            "displayName": "CN=contoso"
+        }
+
+    ],
+    "passwordCredentials": [
+        {
+            "customKeyIdentifier": "lY85bR8r6yWTW6jnciNEONwlVhDyiQjdVLgPDnkI5mA=",
+            "keyId": "4c266507-3e74-4b91-aeba-18a25b450f6e",
+            "endDateTime": "2022-01-27T19:40:33Z",
+            "startDateTime": "2020-04-20T19:40:33Z",
+            "secretText": "mypassword"
+        }
+    ]
+}
+```
+
+## Configure a custom signing key using PowerShell
+Use PowerShell to [instantiate an MSAL Public Client Application](msal-net-initializing-client-applications.md#initializing-a-public-client-application-from-code) and use the [Authorization Code Grant](v2-oauth2-auth-code-flow.md) flow to obtain a delegated permission access token for Microsoft Graph. Use the access token to call Microsoft Graph and configure a custom signing key for the service principal. After configuring the custom signing key, your application code needs to [validate the token signing key](#validate-token-signing-key).
+
+To run this script you need:
+
+- The object ID of your application's service principal, found in the Overview blade of your application's entry in Enterprise Applications in the Azure portal.
+- An app registration to sign in a user and get an access token to call Microsoft Graph. Get the application (client) ID of this app in the Overview blade of the application's entry in App registrations in the Azure portal. The app registration should have the following configuration:
+  - A redirect URI of "http://localhost" listed in the **Mobile and desktop applications** platform configuration.
+  - In **API permissions**, Microsoft Graph delegated permissions **Application.ReadWrite.All** and **User.Read** (make sure you grant Admin consent to these permissions).
+- A user who logs in to get the Microsoft Graph access token. The user should be one of the following Azure AD administrative roles (required to update the service principal):
+  - Cloud Application Administrator
+  - Application Administrator
+  - Global Administrator
+- A certificate to configure as a custom signing key for our application. You can either create a self-signed certificate or obtain one from your trusted certificate authority. The following certificate components are used in the script:
+  - public key (typically a .cer file)
+  - private key in PKCS#12 format (in .pfx file)
+  - password for the private key (pfx file)
+ 
+> [!IMPORTANT]
+> The private key must be in PKCS#12 format since Azure AD doesn't support other format types. Using the wrong format can result in the error "Invalid certificate: Key value is invalid certificate" when using Microsoft Graph to PATCH the service principal with a `keyCredentials` containing the certificate information.
+
+```
+$fqdn="fourthcoffeetest.onmicrosoft.com" # this is used for the 'issued to' and 'issued by' field of the certificate
+$pwd="mypassword" # password for exporting the certificate private key
+$location="C:\\temp" # path to folder where both the pfx and cer file will be written to
+
+# Create a self-signed cert
+$cert = New-SelfSignedCertificate -certstorelocation cert:\currentuser\my -DnsName $fqdn
+$pwdSecure = ConvertTo-SecureString -String $pwd -Force -AsPlainText
+$path = 'cert:\currentuser\my\' + $cert.Thumbprint
+$cerFile = $location + "\\" + $fqdn + ".cer"
+$pfxFile = $location + "\\" + $fqdn + ".pfx"
+ 
+# Export the public and private keys
+Export-PfxCertificate -cert $path -FilePath $pfxFile -Password $pwdSecure
+Export-Certificate -cert $path -FilePath $cerFile
+
+$ClientID = "<app-id>"
+$loginURL       = "https://login.microsoftonline.com"
+$tenantdomain   = "fourthcoffeetest.onmicrosoft.com"
+$redirectURL = "http://localhost" # this reply URL is needed for PowerShell Core 
+[string[]] $Scopes = "https://graph.microsoft.com/.default"
+$pfxpath = $pfxFile # path to pfx file
+$cerpath = $cerFile # path to cer file
+$SPOID = "<service-principal-id>"
+$graphuri = "https://graph.microsoft.com/v1.0/serviceprincipals/$SPOID"
+$password = $pwd  # password for the pfx file
+ 
+ 
+# choose the correct folder name for MSAL based on PowerShell version 5.1 (.Net) or PowerShell Core (.Net Core)
+ 
+if ($PSVersionTable.PSVersion.Major -gt 5)
+    { 
+        $core = $true
+        $foldername =  "netcoreapp2.1"
+    }
+else
+    { 
+        $core = $false
+        $foldername = "net45"
+    }
+ 
+# Load the MSAL/microsoft.identity/client assembly -- needed once per PowerShell session
+[System.Reflection.Assembly]::LoadFrom((Get-ChildItem C:/Users/<username>/.nuget/packages/microsoft.identity.client/4.32.1/lib/$foldername/Microsoft.Identity.Client.dll).fullname) | out-null
+  
+$global:app = $null
+  
+$ClientApplicationBuilder = [Microsoft.Identity.Client.PublicClientApplicationBuilder]::Create($ClientID)
+[void]$ClientApplicationBuilder.WithAuthority($("$loginURL/$tenantdomain"))
+[void]$ClientApplicationBuilder.WithRedirectUri($redirectURL)
+ 
+$global:app = $ClientApplicationBuilder.Build()
+  
+Function Get-GraphAccessTokenFromMSAL {
+    [Microsoft.Identity.Client.AuthenticationResult] $authResult  = $null
+    $AquireTokenParameters = $global:app.AcquireTokenInteractive($Scopes)
+    [IntPtr] $ParentWindow = [System.Diagnostics.Process]::GetCurrentProcess().MainWindowHandle
+    if ($ParentWindow)
+    {
+        [void]$AquireTokenParameters.WithParentActivityOrWindow($ParentWindow)
+    }
+    try {
+        $authResult = $AquireTokenParameters.ExecuteAsync().GetAwaiter().GetResult()
+    }
+    catch {
+        $ErrorMessage = $_.Exception.Message
+        Write-Host $ErrorMessage
+    }
+     
+    return $authResult
+}
+  
+$myvar = Get-GraphAccessTokenFromMSAL
+if ($myvar)
+{
+    $GraphAccessToken = $myvar.AccessToken
+    Write-Host "Access Token: " $myvar.AccessToken
+    #$GraphAccessToken = "eyJ0eXAiOiJKV1QiL ... iPxstltKQ"
+    
+ 
+    #  this is for PowerShell Core
+    $Secure_String_Pwd = ConvertTo-SecureString $password -AsPlainText -Force
+ 
+    # reading certificate files and creating Certificate Object
+    if ($core)
+    {
+        $pfx_cert = get-content $pfxpath -AsByteStream -Raw
+        $cer_cert = get-content $cerpath -AsByteStream -Raw
+        $cert = Get-PfxCertificate -FilePath $pfxpath -Password $Secure_String_Pwd
+    }
+    else
+    {
+        $pfx_cert = get-content $pfxpath -Encoding Byte
+        $cer_cert = get-content $cerpath -Encoding Byte
+        # Write-Host "Enter password for the pfx file..."
+        # calling Get-PfxCertificate in PowerShell 5.1 prompts for password
+        # $cert = Get-PfxCertificate -FilePath $pfxpath
+        $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($pfxpath, $password)
+    }
+ 
+    # base 64 encode the private key and public key
+    $base64pfx = [System.Convert]::ToBase64String($pfx_cert)
+    $base64cer = [System.Convert]::ToBase64String($cer_cert)
+ 
+    # getting id for the keyCredential object
+    $guid1 = New-Guid
+    $guid2 = New-Guid
+ 
+    # get the custom key identifier from the certificate thumbprint:
+    $hasher = [System.Security.Cryptography.HashAlgorithm]::Create('sha256')
+    $hash = $hasher.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($cert.Thumbprint))
+    $customKeyIdentifier = [System.Convert]::ToBase64String($hash)
+ 
+    # get end date and start date for our keycredentials
+    $endDateTime = ($cert.NotAfter).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
+    $startDateTime = ($cert.NotBefore).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
+ 
+    # building our json payload
+    $object = [ordered]@{    
+    keyCredentials = @(       
+         [ordered]@{            
+            customKeyIdentifier = $customKeyIdentifier
+            endDateTime = $endDateTime
+            keyId = $guid1
+            startDateTime = $startDateTime 
+            type = "X509CertAndPassword"
+            usage = "Sign"
+            key = $base64pfx
+            displayName = "CN=fourthcoffeetest" 
+        },
+        [ordered]@{            
+            customKeyIdentifier = $customKeyIdentifier
+            endDateTime = $endDateTime
+            keyId = $guid2
+            startDateTime = $startDateTime 
+            type = "AsymmetricX509Cert"
+            usage = "Verify"
+            key = $base64cer
+            displayName = "CN=fourthcoffeetest"   
+        }
+        )  
+    passwordCredentials = @(
+        [ordered]@{
+            customKeyIdentifier = $customKeyIdentifier
+            keyId = $guid1           
+            endDateTime = $endDateTime
+            startDateTime = $startDateTime
+            secretText = $password
+        }
+    )
+    }
+ 
+    $json = $object | ConvertTo-Json -Depth 99
+    Write-Host "JSON Payload:"
+    Write-Output $json
+ 
+    # Request Header
+    $Header = @{}
+    $Header.Add("Authorization","Bearer $($GraphAccessToken)")
+    $Header.Add("Content-Type","application/json")
+ 
+    try 
+    {
+        Invoke-RestMethod -Uri $graphuri -Method "PATCH" -Headers $Header -Body $json
+    } 
+    catch 
+    {
+        # Dig into the exception to get the Response details.
+        # Note that value__ is not a typo.
+        Write-Host "StatusCode:" $_.Exception.Response.StatusCode.value__ 
+        Write-Host "StatusDescription:" $_.Exception.Response.StatusDescription
+    }
+ 
+    Write-Host "Complete Request"
+}
+else
+{
+    Write-Host "Fail to get Access Token"
+}
+```
+
+## Validate token signing key
+Apps that have claims mapping enabled must validate their token signing keys by appending `appid={client_id}` to their [OpenID Connect metadata requests](v2-protocols-oidc.md#fetch-the-openid-configuration-document). The following example shows the format of the OpenID Connect metadata document you should use:
+
+```
+https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid={client-id}
+```
+
+## Update the application manifest
+For single tenant apps, you can set the `acceptMappedClaims` property to `true` in the [application manifest](reference-app-manifest.md). As documented on the [apiApplication resource type](/graph/api/resources/apiapplication?view=graph-rest-1.0&preserve-view=true#properties), this allows an application to use claims mapping without specifying a custom signing key.
+
+>[!WARNING]
+>Do not set the acceptMappedClaims property to true for multi-tenant apps, which can allow malicious actors to create claims-mapping policies for your app.
+
+The requested token audience is required to use a verified domain name of your Azure AD tenant, which means you should set the `Application ID URI` (represented by the `identifierUris` in the application manifest) for example to `https://contoso.com/my-api` or (simply using the default tenant name) `https://contoso.onmicrosoft.com/my-api`.
+
+If you're not using a verified domain, Azure AD returns an `AADSTS501461` error code with message "_AcceptMappedClaims is only supported for a token audience matching the application GUID or an audience within the tenant's verified domains. Either change the resource identifier or use an application-specific signing key."
+
 ## Advanced claims options
 
 Configure advanced claims options for OIDC applications to expose the same claim as SAML tokens. Also for applications that intend to use the same claim for both SAML2.0 and OIDC response tokens.