> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/da/sikkerhed/enterprise-security/saml2.md).

# SAML2

Konfigurer SAML2-godkendelse i PowerShell Universal med identitetsudbydere som Entra ID, Okta og Shibboleth, herunder metadata og claimtilknytning.

{% hint style="info" %}
SAML2 kræver en [licens](https://store.devolutions.net/package#psu).
{% endhint %}

PowerShell Universal kan konfigureres til at integrere med en SAML2-identitetsudbyder. Denne dokumentation indeholder oplysningerne om konfiguration af PSU med et sådant system.

## Automatisk indlæsning af metadata

PowerShell Universal giver en mekanisme til at indlæse metadatadokumentet direkte fra SAML2-identitetsudbyderen i stedet for manuelt at angive konfigurationsindstillinger. Dette vil indsamle så mange oplysninger som muligt. Entity ID skal stadig angives.

Callback-stien vises øverst i egenskabens modalvindue.

## Manuel angivelse af værdier

### Indstillinger for identitetsudbyderen

De skal konfigurere Deres identitetsudbyder til PowerShell Universal-programmet. De skal opsætte et acceptabelt entity ID og tilknytte attributter. PowerShell Universal kræver, at attributten name er tilknyttet. Attributnavnet skal være følgende.

{% code collapsedlinecount="10" %}

```
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
```

{% endcode %}

De bør knytte dette til den brugeridentitet, De ønsker brugt i PowerShell Universal.

Yderligere attributter kan tilknyttes og vil være tilgængelige under [rolleevaluering](/powershell-universal/da/sikkerhed/security.md#authorization). De finder et eksempel på konfiguration af Shibboleth nedenfor.

### Indstillinger for Entity ID

{% hint style="info" %}
[HTTPS ](/powershell-universal/da/config/hosting.md#configuring-https)er påkrævet til SAML2-godkendelse.
{% endhint %}

Der er flere grundlæggende indstillinger, De kan konfigurere i PowerShell Universal-admin console. For at tilføje understøttelse af SAML2 skal De klikke på Secure > Authentication. I øverste højre hjørne kan De vælge SAML2 fra rullelisten.

Når SAML2-integrationen er tilføjet, kan De konfigurere de grundlæggende indstillinger for kommunikation med Deres identitetsudbyder. De skal som minimum have Entity ID og Identity Provider Entity ID konfigureret.

Typisk er disse Entity ID'er URL'er, der er konfigureret i Deres identitetsudbyder.

Tjenestecertifikatet bruges til at signere anmodninger. Det er ikke påkrævet. Det kan enten være en sti, der er lokal for PSU-tjenesten, eller det entydige navn på et certifikat, der er installeret i det personlige certifikatlager på computeren.

### Yderligere indstillinger

Ud over de indstillinger, der er tilgængelige i admin console, kan De også angive følgende i konfigurationsfilen `authentication.ps1`.

#### ServiceCertificatePassword

Hvis De bruger en filsti til Deres certifikat, og det kræver en adgangskode, kan De angive den via `-ServiceCertificatePassword` i `Set-PSUAuthenticationMethod`. Værdien af denne parameter er en `SecureString`. De kan udnytte SecretManagement-modulet til at indlæse hemmeligheder.

{% code collapsedlinecount="10" %}

```powershell
Set-PSUAuthenticationMethod `
-Type "Saml2" `
-EntityId "http://psu.ironman.local/sp" `
-IdentityProviderEntityId 'https://ironman.local/idp' `
-MetadataAddress 'https://idp.ironman.local/idp/shibboleth' `
-CallbackPath "https://localhost:5000/" `
-ServiceCertificate cert.pfx `
-ServiceCertificatePassword (Get-Secret -Name 'certPassword')
```

{% endcode %}

#### Configure

Parameteren `-Configure` er en scriptblok, der kan bruges til at angive yderligere indstillinger, som ikke eksponeres af `Set-PSUAuthenticationMethod`. Scriptblokken kaldes, når udbyderen konfigureres, og modtager en enkelt parameter, der indeholder et objekt med mulighederne for SAML2-godkendelsen.

Objektet er af typen [Saml2Options](https://github.com/Sustainsys/Saml2/blob/v2.11.0/Sustainsys.Saml2.AspNetCore2/Saml2Options.cs). Underobjektet for SPOptions findes [her](https://github.com/Sustainsys/Saml2/blob/v2.11.0/Sustainsys.Saml2/Configuration/SPOptions.cs).

{% code collapsedlinecount="10" %}

```powershell
Set-PSUAuthenticationMethod `
-Type "Saml2" `
-EntityId "http://psu.ironman.local/sp" `
-IdentityProviderEntityId 'https://ironman.local/idp' `
-MetadataAddress 'https://idp.ironman.local/idp/shibboleth' `
-Configure {
  $options = $args[0]
  $options.SPOptions.DiscoveryServiceUrl = 'https://idp.ironman.local/discovery'
}
```

{% endcode %}

## Eksempel: Entra ID <a href="#example-entra-id" id="example-entra-id"></a>

Konfigurer et Entra ID-virksomhedsprogram i Azure. De kan finde en [trinvis vejledning her](/powershell-universal/da/sikkerhed/enterprise-security/openid-connect.md#configuring-azure-entra-id-azure-active-directory). De skal hente program-id'et og dokumentet med føderationsmetadata samt SAML-P-logonslutpunktet. I Deres appregistrering skal De klikke på knappen Endpoints.

### Trin for trin <a href="#step-by-step" id="step-by-step"></a>

**I PowerShell Universal:**

1. Klik på Secure > Authentication.
2. Tilføj SAML2-godkendelsesudbyder.
3. Klik på knappen Edit Properties.

For Entity ID skal De angive Entra ID-program-id'et med præfikset `spn:`

For eksempel: `spn:2cf33625-e312-4659-a7bd-66ade51a0ea2`

For Identity Provider Entity ID skal De hente entity-id'et fra Federation metadata-dokumentet. Åbn dokumentets URL i en webbrowser.

For Metadata Address skal De indsætte URL'en til Federation metadata-dokumentet.

For Return URL skal De indsætte URL'en til Deres PowerShell Universal-server med stien `/Saml/Acs`.

{% code collapsedlinecount="10" %}

```
https://localhost/Saml2/Acs
```

{% endcode %}

For URL'en til enkeltlogon-tjenesten skal De indsætte SAML-P-logonslutpunktet fra Azure.

Når det er fuldført, skal De gemme indstillingerne og aktivere SAML-udbyderen. Klik på sign out, og gå til URL'en til Deres admin console.

{% code collapsedlinecount="10" %}

```
https://localhost/admin
```

{% endcode %}

De videresendes til Azure for at logge på og omdirigeres tilbage til PowerShell Universal efter godkendelse.

Alle fejl, der opstår, anføres i PowerShell Universal-loggen. Hvis De ikke kan logge på, kan De gå til `/login` for at logge på med en lokal konto.

### Claim-tilknytning

For at levere gruppekrav til PowerShell Universal skal De eksponere gruppekravene fra Deres appregistrering. Klik på Token Configuration, og klik derefter på Add groups claim.

Når De har klikket på Add groups claim, har De mulighed for at vælge, hvilke grupper der leveres. Hvis De vælger All Groups, leveres gruppeclaims til PowerShell Universal

Hvis De vælger Groups assigned to the application, skal De sikre, at De markerer værdien Emit groups as role claims. Denne indstilling kræver en betalt Entra ID-plan.

Hvis De vil tildele en gruppe til Deres appregistrering, skal De finde Deres app i Enterprise Applications og klikke på User and Groups. Klik derefter på Add User\Group, og vælg de grupper, De vil have tildelt Deres program.

Når De har konfigureret groups-claimet i Entra ID, kan De derefter opdatere claim-tilknytningerne i PowerShell Universal til de angivne grupper.

For hver rolle, som De gerne vil tildele til en Entra ID-gruppe, skal De angive Claim Type og Claim Value for den rolle. Jeg har f.eks. en gruppe i mit miljø med id'et 446832da-d4ad-4972-b0a2-eda736129928. Claim Type for dette objekt er <http://schemas.microsoft.com/ws/2008/06/identity/claims/role>.

For at tildele dette til administratorgruppen ville jeg gøre følgende.

Brugere i denne gruppe vil nu være en del af rollen Administrator i PowerShell Universal. Hvis De valgte en anden SAML-gruppeegenskab, kan værdien være anderledes (f.eks. sAMAccountName).

### Group Overages <a href="#group-overages" id="group-overages"></a>

For organisationer med mange grupper vil De gerne begrænse antallet af grupper, der leveres til PowerShell Universal. Dette kan afhjælpe autorisationsproblemer, der opstår, når der leveres for mange grupper, så grænserne i programmet overskrides. I indstillingerne for Enterprise-programmet skal De klikke på enkeltlogon og derefter klikke på knappen Edit under Attributes & Claims.

Klik på groups claim for at se valgmulighederne. De avancerede valgmuligheder giver Dem mulighed for at filtrere de grupper, der leveres til PowerShell Universal-serveren. De kan også konfigurere group claims via tokenkonfigurationen på Application Registration for Enterprise Application.

## Eksempel: Okta

Dette eksempel viser, hvordan De konfigurerer Okta SAML2-godkendelse til brug med PowerShell Universal.

I Okta skal De konfigurere Deres program på samme måde som følgende. HTTPS kræves af SAML2, og De skal medtage URL'en til Deres PSU-instans i Single Sign On URL efterfulgt af `/Saml2/Acs`. Stien skelner mellem store og små bogstaver.

Audience Restriction bør være URL'en til Deres PowerShell Universal-server.

For at Deres brugere kan få adgang til PowerShell Universal, skal De sikre, at de er blevet tildelt Okta-programmet.

På fanen Sign On i Deres program skal De klikke på knappen View SAML setup instructions.

De skal notere de to URL'er og downloade certifikatet til konfiguration af PowerShell Universal. Se næste trin om, hvordan De bruger disse URL'er i filen `authentication.ps1`.

### authentication.ps1

Filen authentication.ps1 bruges til at konfigurere PowerShell Universal.

{% code collapsedlinecount="10" %}

```powershell
Set-PSUAuthenticationMethod -Type "Saml2" `
-EntityId "https://localhost:5001" `
-IdentityProviderEntityId "http://www.okta.com/exk5dvbyzgASPiOFp5d7" `
-CallbackPath "https://localhost:5001" `
-SigningKey "C:\Users\adamr\Downloads\okta.cert" `
-SingleSignOnServiceUrl "https://dev-36706648.okta.com/app/dev-36706648_psusaml_1/exk5dvbyzgASPiOFp5d7/sso/saml"
```

{% endcode %}

| Parameter                | Beskrivelse                                                                                    | Type   |
| ------------------------ | ---------------------------------------------------------------------------------------------- | ------ |
| EntityId                 | Denne værdi skal matche det, De har angivet i Audience Restriction i Okta.                     | string |
| IdentityProviderEntityId | Dette er den værdi, der blev vist på siden View SAML setup instructions.                       | string |
| CallbackPath             | Dette er den sti, som brugeren omdirigeres til, hvis der ikke blev angivet en omdirigeringssti | string |
| SigningKey               | Dette er den certifikatfil, der blev downloadet på siden View SAML setup instructions.         | string |
| SingleSignOnServiceUrl   | Dette er den logon-URL, der blev angivet på siden View SAML setup instructions.                | string |

## Eksempel: Shibboleth

Dette eksempel viser, hvordan Shibboleth konfigureres til brug med PowerShell Universal. Det giver den helt grundlæggende konfiguration og følger ikke nødvendigvis bedste praksis.

Dette forudsætter, at De har installeret Shibboleth Identity Provider v4 med Active Directory-integration.

### ldap.properties

LDAP-egenskaber er konfigureret til godkendelse mod det lokale domæne ved hjælp af en domæneadministratorkonto. LDAP-URL'en er konfigureret, og TLS er deaktiveret.

Nedenfor finder De det fulde eksempel på filen `ldap.properties`.

{% code collapsedlinecount="10" %}

```
# LDAP authentication (and possibly attribute resolver) configuration
# Note, this doesn't apply to the use of JAAS authentication via LDAP

## Authenticator strategy, either anonSearchAuthenticator, bindSearchAuthenticator, directAuthenticator, adAuthenticator
idp.authn.LDAP.authenticator=adAuthenticator

## Connection properties ##
idp.authn.LDAP.ldapURL=ldap://ironman.local:389
idp.authn.LDAP.useStartTLS                     = false
# Time in milliseconds that connects will block
#idp.authn.LDAP.connectTimeout                  = PT3S
# Time in milliseconds to wait for responses
#idp.authn.LDAP.responseTimeout                 = PT3S
# Connection strategy to use when multiple URLs are supplied, either ACTIVE_PASSIVE, ROUND_ROBIN, RANDOM
#idp.authn.LDAP.connectionStrategy               = ACTIVE_PASSIVE

## SSL configuration, either jvmTrust, certificateTrust, or keyStoreTrust
idp.authn.LDAP.sslConfig                       = jvmTrust
## If using certificateTrust above, set to the trusted certificate's path
idp.authn.LDAP.trustCertificates=%{idp.home}/credentials/ldap-server.crt
## If using keyStoreTrust above, set to the truststore path
idp.authn.LDAP.trustStore=%{idp.home}/credentials/ldap-server.truststore

## Return attributes during authentication
idp.authn.LDAP.returnAttributes=passwordExpirationTime,loginGraceRemaining,sn,mail

## DN resolution properties ##

# Search DN resolution, used by anonSearchAuthenticator, bindSearchAuthenticator
# for AD: CN=Users,DC=example,DC=org
idp.authn.LDAP.baseDN=CN=Users,DC=ironman, DC=local
idp.authn.LDAP.subtreeSearch                   = true
idp.authn.LDAP.userFilter=(sAMAccountName={user})
# bind search configuration
# for AD: idp.authn.LDAP.bindDN=adminuser@domain.com
idp.authn.LDAP.bindDN=administrator@ironman.local

# Format DN resolution, used by directAuthenticator, adAuthenticator
# for AD use idp.authn.LDAP.dnFormat=%s@domain.com
idp.authn.LDAP.dnFormat=%s@ironman.local

# pool passivator, either none, bind or anonymousBind
#idp.authn.LDAP.bindPoolPassivator                  = none

# LDAP attribute configuration, see attribute-resolver.xml
# Note, this likely won't apply to the use of legacy V2 resolver configurations
idp.attribute.resolver.LDAP.ldapURL=%{idp.authn.LDAP.ldapURL}
idp.attribute.resolver.LDAP.connectTimeout=%{idp.authn.LDAP.connectTimeout:PT3S}
idp.attribute.resolver.LDAP.responseTimeout=%{idp.authn.LDAP.responseTimeout:PT3S}
idp.attribute.resolver.LDAP.connectionStrategy=%{idp.authn.LDAP.connectionStrategy:ACTIVE_PASSIVE}
idp.attribute.resolver.LDAP.baseDN=%{idp.authn.LDAP.baseDN:undefined}
idp.attribute.resolver.LDAP.bindDN=%{idp.authn.LDAP.bindDN:undefined}
idp.attribute.resolver.LDAP.useStartTLS=%{idp.authn.LDAP.useStartTLS:true}
idp.attribute.resolver.LDAP.trustCertificates=%{idp.authn.LDAP.trustCertificates:undefined}
idp.attribute.resolver.LDAP.searchFilter=(sAMAccountName=$resolutionContext.principal)

# LDAP pool configuration, used for both authn and DN resolution
#idp.pool.LDAP.minSize                          = 3
#idp.pool.LDAP.maxSize                          = 10
#idp.pool.LDAP.validateOnCheckout               = false
#idp.pool.LDAP.validatePeriodically             = true
#idp.pool.LDAP.validatePeriod                   = PT5M
#idp.pool.LDAP.validateDN                       =
#idp.pool.LDAP.validateFilter                   = (objectClass=*)
#idp.pool.LDAP.prunePeriod                      = PT5M
#idp.pool.LDAP.idleTime                         = PT10M
#idp.pool.LDAP.blockWaitTime                    = PT3S

```

{% endcode %}

### relying-party.xml

Filen `relying-party.xml` er blevet opdateret for at aktivere open IdP. Det betyder, at et hvilket som helst entity ID kan kommunikere med identitetsudbyderen. De kan også konfigurere dette, så bestemte entity ID'er håndhæves. Standardkonfigurationen er også justeret til at bruge bean'en `SAML2.AttributeQuery`.

{% code collapsedlinecount="10" %}

```
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:util="http://www.springframework.org/schema/util"
       xmlns:p="http://www.springframework.org/schema/p"
       xmlns:c="http://www.springframework.org/schema/c"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
                           http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd
                           http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd"
                           
       default-init-method="initialize"
       default-destroy-method="destroy">

    <!--
    Unverified RP configuration, defaults to no support for any profiles. Add <ref> elements to the list
    to enable specific default profile settings (as below), or create new beans inline to override defaults.
    
    "Unverified" typically means the IdP has no metadata, or equivalent way of assuring the identity and
    legitimacy of a requesting system. To run an "open" IdP, you can enable profiles here.
    -->
    <bean id="shibboleth.UnverifiedRelyingParty" parent="RelyingParty">
        <property name="profileConfigurations">
            <list>
			<bean parent="SAML2.SSO" p:encryptAssertions="false" />
            </list>
        </property>
    </bean>

    <!-- Default configuration, with default settings applied for all profiles. -->
    <bean id="shibboleth.DefaultRelyingParty" parent="RelyingParty">
        <property name="profileConfigurations">
            <list>
                <!-- SAML 1.1 and SAML 2.0 AttributeQuery are disabled by default. -->
                <!--
                <bean parent="Shibboleth.SSO" />
                <ref bean="SAML1.AttributeQuery" />
                <ref bean="SAML1.ArtifactResolution" />
                -->
                <bean parent="SAML2.SSO" />
                <ref bean="SAML2.ECP" />
                <ref bean="SAML2.Logout" />
                <ref bean="SAML2.AttributeQuery" />
                <ref bean="SAML2.ArtifactResolution" />
                <ref bean="Liberty.SSOS" />
            </list>
        </property>
    </bean>
</beans>

```

{% endcode %}

### attribute-resolver.xml

Filen `attribute-resolver.xml` er blevet opdateret til at bruge LDAPDirectory Data Connector. Den indlæser e-mailadressen, fornavnet, SN og visningsnavnet fra Active Directory. Den knytter derefter Principal Name, som vil være brugernavnet for den bruger, der logger på, til den påkrævede claimtype ved hjælp af en attribute encoder.

{% code collapsedlinecount="10" %}

```
<?xml version="1.0" encoding="UTF-8"?>
<!--
    This file is an EXAMPLE configuration file containing some example attributes
    based on some commonly used approaches when LDAP is the principal data source.
     
    Not all attribute definitions or data connectors are demonstrated, but some
    LDAP attributes common to Shibboleth deployments (and some not so common) are
    included.

    This example is in no way usable as a substitute for reading the documentation.    
-->
<AttributeResolver
        xmlns="urn:mace:shibboleth:2.0:resolver"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:mace:shibboleth:2.0:resolver http://shibboleth.net/schema/idp/shibboleth-attribute-resolver.xsd">

    <!-- ========================================== -->
    <!--      Attribute Definitions                 -->
    <!-- ========================================== -->

    <!-- Simple attributes are exported directly from the LDAP connector. -->

    <AttributeDefinition id="uid" xsi:type="PrincipalName" />
    <AttributeDefinition id="username" xsi:type="PrincipalName">
         <AttributeEncoder xsi:type="SAML2String" name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" friendlyName="displayName" encodeType="false" />
    </AttributeDefinition>

    <!-- ========================================== -->
    <!--      Data Connectors                       -->
    <!-- ========================================== -->

    <!-- Example LDAP Connector -->

    <DataConnector id="myLDAP" xsi:type="LDAPDirectory"
        ldapURL="%{idp.attribute.resolver.LDAP.ldapURL}"
        baseDN="%{idp.attribute.resolver.LDAP.baseDN}" 
        principal="%{idp.attribute.resolver.LDAP.bindDN}"
        principalCredential="%{idp.attribute.resolver.LDAP.bindDNCredential}"
        useStartTLS="%{idp.attribute.resolver.LDAP.useStartTLS:true}"
        connectTimeout="%{idp.attribute.resolver.LDAP.connectTimeout}"
        responseTimeout="%{idp.attribute.resolver.LDAP.responseTimeout}"
        connectionStrategy="%{idp.attribute.resolver.LDAP.connectionStrategy}"
        noResultIsError="true"
        multipleResultsIsError="true"
        excludeResolutionPhases="c14n/attribute"
        exportAttributes="mail displayName sn givenName">
        <FilterTemplate>
            <![CDATA[
                %{idp.attribute.resolver.LDAP.searchFilter}
            ]]>
        </FilterTemplate>
        <ConnectionPool
            minPoolSize="%{idp.pool.LDAP.minSize:3}"
            maxPoolSize="%{idp.pool.LDAP.maxSize:10}"
            blockWaitTime="%{idp.pool.LDAP.blockWaitTime:PT3S}"
            validatePeriodically="%{idp.pool.LDAP.validatePeriodically:true}"
            validateTimerPeriod="%{idp.pool.LDAP.validatePeriod:PT5M}"
            validateDN="%{idp.pool.LDAP.validateDN:}"
            validateFilter="%{idp.pool.LDAP.validateFilter:(objectClass=*)}"
            expirationTime="%{idp.pool.LDAP.idleTime:PT10M}"/>
    </DataConnector>

</AttributeResolver>

```

{% endcode %}

### attribute-filter.xml

Filen `attribute-filter.xml` er blevet opdateret, så den frigiver flere af de attributter, der er tilknyttet af dataforbindelsen LDAPDirectory, samt det brugernavn, der skal bruges som identitet i PowerShell Universal.

{% code collapsedlinecount="10" %}

```
<?xml version="1.0" encoding="UTF-8"?>
<!-- 
    This file is an EXAMPLE policy file.  While the policy presented in this 
    example file is illustrative of some simple cases, it relies on the names of
    non-existent example services and the example attributes demonstrated in the
    default attribute-resolver.xml file.

    This example does contain some usable "general purpose" policies that may be
    useful in conjunction with specific deployment choices, but those policies may
    not be applicable to your specific needs or constraints.    
-->
<AttributeFilterPolicyGroup id="ShibbolethFilterPolicy"
        xmlns="urn:mace:shibboleth:2.0:afp"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:mace:shibboleth:2.0:afp http://shibboleth.net/schema/idp/shibboleth-afp.xsd">

<AttributeFilterPolicy id="example1">
        <PolicyRequirementRule xsi:type="ANY" />
        <AttributeRule attributeID="username">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="displayName">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="uid">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="mail">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="sn">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
    </AttributeFilterPolicy>
 


</AttributeFilterPolicyGroup>

```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.devolutions.net/powershell-universal/da/sikkerhed/enterprise-security/saml2.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.