Crear un formulario de restablecimiento de contraseña de Azure Entra ID con Microsoft Graph y PowerShell Universal

En esta entrada veremos cómo crear un formulario de restablecimiento de contraseña para Azure Entra ID con Microsoft Graph y PowerShell Universal. Usaremos los módulos Microsoft.Graph.Authentication y Microsoft.Graph.Users para conectarnos a Graph como el usuario actual y restablecer la contraseña de otro usuario.

Configuración de Azure Entra ID

El primer paso es configurar un registro de aplicación de Azure Entra ID para PowerShell Universal. Así los usuarios podrán iniciar sesión con OpenID Connect y sus credenciales de Entra ID. También configuraremos los permisos de API para dar acceso a Microsoft Graph.

En el registro de aplicación, defina la ruta de devolución de llamada hacia el servidor de PowerShell Universal. HTTPS es obligatorio; el puerto puede ser el que use PowerShell Universal. Incluya una ruta de devolución de llamada de inicio de sesión. Configurará el mismo valor en PowerShell Universal.

A continuación, asegúrese de que estén seleccionados los siguientes tipos de token.

Configure ahora los permisos que delegará a la aplicación y al usuario que inicia sesión. Estos permisos son necesarios para buscar usuarios y restablecer sus cuentas. El permiso Directory.AccessAsUser.All es necesario para establecer la contraseña de otro usuario. No se puede conceder a una aplicación y debe proporcionarse por delegación. Los usuarios del grupo Global Administrator tienen este permiso.

Por último, genere un nuevo secreto de cliente para usarlo en PowerShell Universal.

Configurar la autenticación en PowerShell Universal

Ahora que el registro de aplicación está en Entra ID, configure PowerShell Universal para autenticar al usuario y proporcionar un token de acceso a Microsoft Graph. Pulse Security > Authentication y añada OpenID Connect a la lista de métodos. En las propiedades, conecte el registro de aplicación a PowerShell Universal.

Deberá indicar los siguientes valores. Son ejemplos; los suyos diferirán según su inquilino:

• Callback Path: https://localhost:5001/signin-oidc. Es la misma URL que en su registro de aplicación.
• Client ID: 21a267e2-893d-4e0d-a85e-ff21757f082b. El ID del registro de aplicación, en la página Overview.
• Client Secret: xyz123. El secreto de cliente que generó en el registro de aplicación.
• Authority: https://login.microsoftonline.com/3eca8ff3-f62f-431b-88f5-b40183116004. El servicio de inicio de sesión de Microsoft Entra ID. El GUID es el ID de su inquilino.
• Resource: https://graph.microsoft.com. El recurso al que el token de acceso debe dar acceso.
• Save Tokens: true. PowerShell Universal debe guardar el token de acceso para que la app pueda usarlo.
• Response Type: id_token token. Entra ID debe devolver tokens para que pueda delegar el acceso más adelante.
• Scope: openid profile groups offline_access. Los tokens de acceso deben incluir pertenencia a grupos e información de perfil.

Cuando termine la configuración, podrá iniciar sesión en PowerShell Universal con OpenID Connect. Para validarlo, cierre la sesión de su cuenta y pulse el botón de inicio de sesión con OpenID Connect.

Instalar los módulos de Microsoft Graph

Deberá instalar los siguientes módulos de Graph para usar este ejemplo. Las versiones usadas aquí se indican a continuación.

• Microsoft.Graph.Authentication 2.26.1
• Microsoft.Graph.Users 2.26.1

Puede hacerlo yendo a Platform > Modules > Galleries en la consola de administración. Usamos la siguiente versión de PowerShell Universal para esta demo.

• PowerShell Universal 5.5.0

App de restablecimiento de contraseña

Ahora que la autenticación está configurada, podemos crear la app de restablecimiento de contraseña. Primero, almacene algunas variables para acceder a Microsoft Graph mediante el registro de aplicación. Vaya a Platform > Variables y cree las siguientes variables.

• PSUMgTenantId: 3eca8ff3-f62f-431b-88f5-b40183116004. El mismo ID de inquilino que en la configuración OIDC.
• PSUMgClientSecret: una credencial PS Credential cuyo nombre de usuario es el ID del registro de aplicación (21a267e2-893d-4e0d-a85e-ff21757f082b) y cuya contraseña es el secreto de cliente.

Cuando haya creado estas variables, vaya a Apps > Apps y cree una app nueva. Pulse Edit Code para definir el contenido de la app.

# Connect as the application. Use the process context scope to avoid affecting other apps.
# We are passing in the tenant ID and client secret.
# We are connecting when the app is starting to avoid connecting every time the page is loaded.
Connect-MgGraph -TenantId $PSUMgTenantId -ClientSecretCredential $Secret:PSUMgClientSecret -ContextScope Process -NoWelcome

New-UDApp -Content {

    New-UDForm -Children {
        New-UDAutocomplete -OnLoadOptions {
            Get-MgUser -ConsistencyLevel eventual -Count userCount -Search "`"DisplayName:$Body`"" | ForEach-Object {
                New-UDAutocompleteOption -Name $_.DisplayName -Value $_.Id
            }
        } -Label "User" -Id 'UserId'
        New-UDTextbox -Label 'Password' -Type password -Id 'Password'
        New-UDTextbox -Label 'Confirm Password' -Type password -Id 'ConfirmPassword'
    } -OnValidate {
        if ([string]::IsNullOrEmpty($EventData.UserId)) {
            New-UDValidationResult -ValidationError "User is required"
            return
        }

        if ([string]::IsNullOrEmpty($EventData.Password) -or [string]::IsNullOrEmpty($EventData.ConfirmPassword)) {
            New-UDValidationResult -ValidationError "Password is required"
            return
        }

        if ($EventData.Password -cne $EventData.ConfirmPassword) {
            New-UDValidationResult -ValidationError "Passwords do not match"
            return
        }

        $MgUser = Get-MgUser -UserId $EventData.UserId
        if ($MgUser -eq $null) {
            New-UDValidationResult -ValidationError "Unable to locate user."
            return
        }

        New-UDValidationResult -Valid
    } -OnSubmit {

        if ($AccessToken -eq $null) {
            throw "Access Token is required. Ensure you have Save Tokens enabled in your OpenID Connect authentication method."
        }

        Set-PSUCache -Key "MgAccessToken_$User" -Value $AccessToken

        $PasswordKey = (New-Guid).ToString()
        Set-PSUCache -Key $PasswordKey -Value $EventData.Password -AbsoluteExpiration (Get-Date).AddMinutes(5)

        Invoke-PSUScript -Name 'MgResetPassword.ps1' -Parameters @{
            ResetUser = $EventData.UserId
            PasswordKey = $PasswordKey
        } -Wait -Integrated | Out-Null

        Show-UDSnackbar -Message "Password reset!" -Variant success
    }
}

La app se conecta a Graph como aplicación al arrancar, con Connect-MgGraph y el ámbito de contexto de proceso para no afectar a otras apps. El formulario busca usuarios con Get-MgUser, comprueba que las contraseñas coincidan y luego almacena en caché el token de acceso del usuario conectado y la nueva contraseña. La caché evita guardar el token de acceso en texto claro en el historial de trabajos y usa la caché temporal para que los valores no persistan entre reinicios.

El formulario llama después a MgResetPassword.ps1 con Invoke-PSUScript. Un script aísla la conexión a Microsoft Graph para que quede ligada solo a este usuario (varias personas pueden usar la app a la vez) y ofrece un historial automático de trabajos que indica qué operador restableció qué cuenta.

La app resultante se ve así.

Script de restablecimiento

Ahora que la interfaz de usuario está definida, configure el script de restablecimiento que realiza la operación. Pulse Automation > Scripts y cree un script nuevo. Nombre el script MgResetPassword.ps1. Pulse la pestaña Execution y establezca el entorno en PowerShell 7. Una vez creado, pulse Edit Code e introduzca lo siguiente.

param($ResetUser, $PasswordKey)

try {
    $Password = Get-PSUCache -Key $PasswordKey
    if (-not $Password) {
        throw "Target password not found."
    }

    $AccessToken = Get-PSUCache -Key "MgAccessToken_$($UAJob.Identity.Name)"
    if (-not $AccessToken) {
        throw "Access token not found for $($UAJob.Identity.Name)"
    }

    Connect-MgGraph -AccessToken ($AccessToken | ConvertTo-SecureString -AsPlainText -Force) -NoWelcome

    $User = Get-MgUser -UserId $ResetUser

    if ($User -eq $null) {
        throw "Failed to look up user: $ResetUser"
    }

    $password = @{
        Password = $Password
        ForceChangePasswordNextSignIn = $false
    }
    Update-MgUser -UserId $User.Id -PasswordProfile $password
} finally {
    Remove-PSUCache -Key $PasswordKey
}

El script lee la contraseña y el token de acceso del operador actual en la caché, se conecta a Graph con ese token, busca al usuario de destino y llama a Update-MgUser con un perfil de contraseña. Después quita la contraseña de la caché.

Con el script creado, pruebe la app. Deberá iniciar sesión como un usuario con los permisos de Entra ID adecuados para estas operaciones. Tras enviar el formulario, verá una notificación de éxito y un trabajo nuevo en el historial.

¿Listo para crear? Descargue PowerShell Universal.