MC798676 – Change coming to the format of IP addresses containing IPV4 embedded in IPV6 addresses within token claims (archived)

Product:

Microsoft 365 Apps, Microsoft 365 suite

Platform:

Web, World tenant

Status:

Change type:

User impact, Admin impact

Links:

Details:

Summary:
The format of IP addresses embedded in IPV6 within token claims is changing, impacting the 'ipaddr' claim in JWTs. Organizations using custom applications that depend on the string format of this claim need to update their code. The change takes effect on July 8th, 2024. No action is required if there's no dependency on the string format.

Details:
Note: If your organization does not use custom applications or your custom applications do not take a dependency on the string format of the 'ipaddr' claim from the access token or id token, there should not be any impact and no action is required."
Action may be required: The format of IP addresses containing IPV4 embedded in IPV6 addresses within token claims is changing.
The Microsoft identity platform implements security tokens as JSON Web Tokens (JWTs) that contain claims. Claims are name or value pairs that relay facts about the token subject. Applications can use claims for the following various tasks: Validate the token, Identify the token subject's tenant, display user information, identify client's IP Address etc.
One of the claims in the token is 'ipaddr' which is a string and refers to the IP address the user authenticates from.
The format of certain IPV6 addresses containing IPV4 address is altered to display as all IPV6 addresses. The impacted ipv6 addresses are those of a format xxxx:xxxx:xxxx:xxxx:200:5efe:xxxx:xxxx, i.e., where 7, 6, 5, and 4 octets have values '0x02, '0x00', '0x5e', '0xfe' correspondingly.
Currently these IP addresses are serialized with embedded ipv4 address like this: xxxx:xxxx:xxxx:xxxx:200:5efe:YYY.YYY.YYY.YYY, where 'YYY' is number from 0 to 255.
Once the changes go into effect, these IP Addresses will be serialized as xxxx:xxxx:xxxx:xxxx:200:5efe:xxxx:xxxx where x is a hex digit (0-9, a-f)
For example:
Current format: "2001:558:1416:0:200:5efe:169.152.178.93"
Format after the change: "2001:558:1416:0:200:5efe:a998:b25d"
Please note that despite the string format looking different, both IP addresses remain the same. The change would impact both access tokens and id tokens; and the affected claims is 'ipaddr' claim.
ClaimFormatDescription
ipaddrStringThe IP address the user authenticated from.

The 'ipaddr' claim is included in the V1.0 token if applicable and included in the V2.0 token if the application requests them using optional claims. Please look at Access token claims reference - Header claims for more details.
[When this will happen:]
The change will go into effect on July 8th, 2024.

Change Category:
XXXXXXX ... free basic plan only

Scope:
XXXXXXX ... free basic plan only

Release Phase:

Created:
2024-06-05

updated:
2024-08-10

Task Type

XXXXXXX ... free basic plan only

Docu to Check

XXXXXXX ... free basic plan only

MS Preperations

XXXXXXX ... free basic plan only

MS Urgency

XXXXXXX ... free basic plan only

MS workload name

XXXXXXX ... free basic plan only

Direct effects for Operations**

- Impact on IT Operations
- Potential downtime for custom applications that rely on the 'ipaddr' claim in JWTs if not updated in time.
- Roles impacted: Application Developers, IT Operations Team
- Increased workload for IT administrators to review and update custom applications to accommodate the new format.
- Roles impacted: IT Administrators, Application Support Teams

- Impact on IT Services
- Disruption in authentication processes for applications that do not handle the new 'ipaddr' format, leading to possible service outages.
- Roles impacted: Service Managers, IT Support Teams
- Need for additional testing and validation of applications post-update to ensure compliance with the new token format.
- Roles impacted: Quality Assurance Teams, IT Security Teams

- Impact on IT Users
- Users may experience authentication failures or degraded service if their applications are not updated to handle the new 'ipaddr' format.
- Roles impacted: End Users, Business Unit Leaders
- Increased support requests from users facing issues related to authentication due to the change, leading to potential delays in service.
- Roles impacted: Helpdesk Staff, User Support Teams

- Dependencies and Interdependencies
- Custom applications may have dependencies on other services (e.g., logging, monitoring) that also need to be updated to handle the new 'ipaddr' format.
- Roles impacted: System Architects, Integration Teams
- Changes in the token format may affect third-party integrations that rely on the 'ipaddr' claim, necessitating updates across multiple systems.
- Roles impacted: Vendor Management Teams, Integration Specialists

- Compliance and Security Considerations
- Organizations must ensure that their applications comply with the new format to avoid security vulnerabilities related to improper token handling.
- Roles impacted: Compliance Officers, Security Analysts
- Potential need for training sessions or documentation updates for developers and administrators to understand the implications of the change.
- Roles impacted: Training Coordinators, Documentation Specialists

References:
- [Microsoft Entra Identity Platform Access Token Claims Reference](https://learn.microsoft.com/entra/identity-platform/access-token-claims-referenceheader-claims)
- [System.Net.IPAddress.Parse Method](https://learn.microsoft.com/dotnet/api/system.net.ipaddress.parse?view=net-8.0)

Opportunities**

XXXXXXX ... free basic plan only

Potentional Risks**

XXXXXXX ... free basic plan only

Data Protection**

XXXXXXX ... paid membership only

Hypothetical Work Council Statement**

XXXXXXX ... paid membership only

DPIA**

XXXXXXX ... paid membership only