Configure token lifetime policies (preview)

  • How-to

In the following steps, you'll implement a common policy scenario that imposes new rules for token lifetime. It's possible to specify the lifetime of an access, SAML, or ID token issued by the Microsoft identity platform. This can be set for all apps in your organization or for a specific app or principal. They can also be set for multi-organizations (multitenant application). You might want to increase the token lifetime so that a script will run for more than an hour. Many Microsoft libraries, such as Microsoft Graph PowerShell SDK, extend the token lifetime as needed and you don't need to makes changes to the access token policy. For more information, see configurable token lifetimes.

Prerequisites

To get started, download the latest Microsoft Graph PowerShell SDK.

Create a policy and assign it to an app

In the following steps, you'll create a policy that requires users to authenticate less frequently in your web app. Assign the policy to an app, which sets the lifetime of the access/ID tokens to 4 hours for your web app.

Install-Module Microsoft.Graph

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes  "Policy.ReadWrite.ApplicationConfiguration","Policy.Read.All","Application.ReadWrite.All"

# Create a token lifetime policy
$params = @{
  Definition = @('{"TokenLifetimePolicy":{"Version":1,"AccessTokenLifetime":"4:00:00"}}') 
    DisplayName = "WebPolicyScenario"
  IsOrganizationDefault = $false
}
$tokenLifetimePolicyId=(New-MgPolicyTokenLifetimePolicy -BodyParameter $params).Id

# Display the policy
Get-MgPolicyTokenLifetimePolicy -TokenLifetimePolicyId $tokenLifetimePolicyId

# Assign the token lifetime policy to an app
$params = @{
  "@odata.id" = "https://microsoftgraph.chinacloudapi.cn/v1.0/policies/tokenLifetimePolicies/$tokenLifetimePolicyId"
}

$applicationObjectId="aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"

New-MgApplicationTokenLifetimePolicyByRef -ApplicationId $applicationObjectId -BodyParameter $params

# List the token lifetime policy on the app
Get-MgApplicationTokenLifetimePolicy -ApplicationId $applicationObjectId

# Remove the policy from the app
Remove-MgApplicationTokenLifetimePolicyByRef -ApplicationId $applicationObjectId -TokenLifetimePolicyId $tokenLifetimePolicyId

# Delete the policy
Remove-MgPolicyTokenLifetimePolicy -TokenLifetimePolicyId $tokenLifetimePolicyId

Create a policy and assign it to a service principal

In the following steps, you'll create a policy that requires users to authenticate less frequently in your web app. Assign the policy to service principal, which sets the lifetime of the access/ID tokens to 8 hours for your web app.

  1. Create a token lifetime policy.

    POST https://microsoftgraph.chinacloudapi.cn/v1.0/policies/tokenLifetimePolicies
Content-Type: application/json
{
    "definition": [
        "{\"TokenLifetimePolicy\":{\"Version\":1,\"AccessTokenLifetime\":\"8:00:00\"}}"
    ],
    "displayName": "Contoso token lifetime policy",
    "isOrganizationDefault": false
}

  2. Assign the policy to a service principal.

    POST https://microsoftgraph.chinacloudapi.cn/v1.0/servicePrincipals/00001111-aaaa-2222-bbbb-3333cccc4444/tokenLifetimePolicies/$ref
Content-Type: application/json
{
  "@odata.id":"https://microsoftgraph.chinacloudapi.cn/v1.0/policies/tokenLifetimePolicies/00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
}

  3. List the policies on the service principal.

    GET https://microsoftgraph.chinacloudapi.cn/v1.0/servicePrincipals/00001111-aaaa-2222-bbbb-3333cccc4444/tokenLifetimePolicies

  4. Remove the policy from the service principal.

    DELETE https://microsoftgraph.chinacloudapi.cn/v1.0/servicePrincipals/00001111-aaaa-2222-bbbb-3333cccc4444/tokenLifetimePolicies/00aa00aa-bb11-cc22-dd33-44ee44ee44ee/$ref

View existing policies in a tenant

To see all policies that have been created in your organization, run the Get-MgPolicyTokenLifetimePolicy cmdlet. Any results with defined property values that differ from the defaults listed above are in scope of the retirement.

  1. Run the Get-MgPolicyTokenLifetimePolicy to see all policies that have been created in your organization.

    Get-MgPolicyTokenLifetimePolicy

  2. Run List appliesTo with any of your policy IDs to see which apps are linked to a specific policy that you identified.

    GET https://microsoftgraph.chinacloudapi.cn/v1.0/policies/tokenLifetimePolicies/4d2f137b-e8a9-46da-a5c3-cc85b2b840a4/appliesTo