What is Federation Authentication

Federated authentication device enrollment

  • 12 minutes to read

This section provides an example of the mobile device enrollment protocol using federated authentication policy. When the authentication policy is set to Federated, the enrollment client uses the web authentication broker to obtain a security token .When the authentication policy is set to Federated, the web authentication broker is leveraged by the enrollment client to get a security token. The enrollment client calls the web authentication broker API within the response message to start the process authentication broker API within the response message to start the process. The server should build the web authentication broker pages to fit the device screen and be consistent with the existing registration UI hould build the web authentication broker pages to fit the device screen and should be consistent with the existing enrollment UI. The opaque security token that is returned from the broker as an end page is used by the enrollment client as the device security secret during the client certificate request call.

The element the discovery response message specifies web authentication broker page start URL.

For details about the Microsoft mobile device enrollment protocol for Windows 10, see [MS-MDE2]: Mobile Device Enrollment Protocol Version 2.

In this topic

Discovery service
Enrollment policy web service
Enrollment web service

For the list of enrollment scenarios not supported in Windows 10, see Enrollment scenarios not supported.

Discovery service

The discovery web service provides the configuration information necessary for a user to enroll a phone with a management service. The service is a restless web service over HTTPS ( The service is a restful web service over HTTPS (server authentication only).

Note

The Discovery Service administrator must create a host with the enterprise address registry. domain_name.com The administrator of the discovery service must create a host with the address enterprise enrollment.domain_name.com.

The automatic discovery flow of the device uses the domain name of the email address that was submitted to the Workplace settings screen during sign in. The automatic discovery system creates a URI that uses this host name by appending the subdomain "enterpriseenrollment" to the domain of the email address and adding the path "/EnrollmentServer/Discovery.svc" system constructs a URI that uses this hostname by appending the subdomain “enterpriseenrollment” to the domain of the email address, and by appending the path “/EnrollmentServer/Discovery.svc”. For example, if the email address is "sample @ contoso. com ", the resulting URI for the first get request would be: http: /enterpriseenrollment.contoso.com/EnrollmentServer/Discovery.svc For example, if the ema il address is “[email protected]”, the resulting URI for first Get request would be: http://enterpriseenrollment.contoso.com/EnrollmentServer/Discovery.svc

The first request is a standard HTTP GET request.

The following example shows a request via HTTP GET to the discovery server given [email protected] as the email address .

After the device has received a response from the server, the device sends a POST request to enterpriseenrollment. domain_name/EnrollmentServer/Discovery.svc. After the device gets a response from the server, the device sends a POST request to enterpriseenrollment.domain_name/EnrollmentServer/Discovery.svc. After receiving another response from the server (which should tell the device where the registration server is located), the next message sent by the device is sent to enterpriseenrollment. domain_name After it gets another response from the server (which should tell the device where the enrollment server is), the next message sent from the device is to enterpriseenrollment.domain_name to the enrollment server.

The following logic is applied:

  1. The device first tries HTTPS. If the server cert is not trusted by the device, the HTTPS fails.
  2. If that fails, the device tries HTTP to see whether it is redirected:
    • If the device is not redirected, it prompts the user for the server address.
    • If the device is redirected, it prompts the user to allow the redirect.

The following example shows a request via an HTTP POST command to the discovery web service given user @ contoso.com as the email address

The following example shows the discovery service request.

The discovery response is in the XML format and includes the following fields:

  • Enrollment service URL (EnrollmentServiceUrl) - Specifies the URL of the enrollment endpoint that is exposed by the management service. The device should call this URL after the user has been authenticated. This field is mandatory.
  • Authentication policy (AuthPolicy) - Indicates what type of authentication is required For the MDM server, OnPremise is the supported value, which means that when the user accesses the Administration Service URL For the MDM server, OnPremise is the supported value, which means that the user will be authenticated when calling the management service URL. This field is mandatory.
  • In Windows, Federated is added as another supported value. This allows the server to leverage the Web Authentication Broker to perform customized user authentication, and term of usage acceptance.

Note

The Transfer-Encoding may specify Transfer-Encoding Chunked. it must be sent as a message. The HTTP server response must not set Transfer-Encoding to Chunked; it must be sent as one message.

When authentication policy is set to be Federated, Web Authentication Broker (WAB) will be leveraged by the enrollment client to get a security token. The WAB start page URL is provided by the discovery service in the response message. The enrollment client will call the WAB API within the response message to start the WAB process. WAB pages are server hosted web pages.The server should create these pages to work well to fit the device screen and be as consistent as possible with other builds in the MDM enrollment user interface The server should build those pages to fit the device screen nicely and be as consistent as possible to other builds in the MDM enrollment UI. The opaque security token returned by WAB as the end page is used by the registration client as a device security secret during the client certificate registration request call . The opaque security token that is returned from WAB as an endpage will be used by the enrollment client as the device security secret during the client certificate enrollment request call.

Note

Instead of relying on the user agent string that is passed during authentication to get information, such as the OS version, use the following guidance:

  • Parse the OS version from the data sent up during the discovery request.
  • Append the OS version as a parameter in the AuthenticationServiceURL.
  • Parse out the OS version from the AuthenticiationServiceURL when the OS sends the response for authentication.

A new XML tag, AuthenticationServiceUrl, is introduced in the DiscoveryResponse XML to allow the server to specify the WAB page start URL. For Federated authentication, this XML tag must exist.

Note

The enrollment client is agnostic with regards to the protocol flows for authenticating and returning the security token While the server might prompt for user credentials directly or enter into a federation protocol with another server and directory service, the enrollment client is agnostic to all of this. To stay agnostic, all are Protocol flows in connection with the authentication, which concern the registration client, passive, i. H. browser- implemented. To remain agnostic, all protocol flows pertaining to authentication that involve the enrollment client are passive, that is, browser-implemented.

The following are the explicit requirements for the server.

  • The element must support HTTPS.
  • The authentication server must use a device trusted root certificate. Otherwise, the WAP call will fail.
  • WP doesn't support Window Integrated Authentication (WIA) for ADFS during WAB authentication.ADFS 2012 R2, if used, must be configured to do so ADFS 2012 R2 if used needs to be configured to not attempt WIA for Windows device.

The enrollment client issues an HTTPS request as follows:

  • is of the form ms-app: // string is of the form ms-app: // string
  • registration login page. is the name of the enrolling user, for example, [email protected] as input by the user in an enrollment sign in The value of this attribute serves as a hint that can be used by the authentication server as part of the authentication.

After authentication is complete, the auth server should return an HTML form document with a POST method action of appid identified in the query string parameter.

Note

Typically, to make an application compliant with strict content security policies, you need to make some changes to HTML templates and client-side code, add the policy header, and test that everything works properly after the policy is deployed Content Security Policy, it is usually necessary to make some changes to HTML templates and client-side code, add the policy header, and test that everything works properly once the policy is deployed.

The server must send a POST to a redirect URL of the form ms-app: // string (the URL scheme is ms-app) as specified in the POST method action of the form ms-app: // string (the URL scheme is ms-app) as indicated in the POST method action. The value of the security token is the base64-encoded string "http://docs.oasis-open.org/ wss / 2004/01 / oasis-200401-wss-wssecurity-secext-1.0.xsd \ # base64binary "in the EncodingType attribute. The security token value is the base64-encoded string" http: // docs. oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd#base64binary "contained in the EncodingType attribute.Windows executes the binary encoding when it references it Windows does the binary encode when it sends it back to enrollment server, in the form it is just HTML encoded st opaque to the registration client. The client does not interpret the string. This string is opaque to the enrollment client; the client does not interpret the string.

The following example shows a response received from the discovery web service which requires authentication via WAB.

Enrollment policy web service

Policy service is optional. If no policies are specified, the default minimum key length is 2k and the hash algorithm is SHA-1.By default, if no policies are specified, the minimum key length is 2k and the hash algorithm is SHA-1.

This web service implements the X.509 Certificate Enrollment Policy Protocol (MS-XCEP) specification that allows customizing certificate enrollment to match different security needs of enterprises at different times (cryptographic agility). The service processes the GetPolicies message from the client, authenticates the client and gives matching registration policies in the GetPoliciesResponse message The service processes the GetPolicies message from the client, authenticates the client, and returns matching enrollment policies in the GetPoliciesResponse message.

For Federated authentication policy, The security token credential is provided in a request message using the element [WSS The security token is retrieved as described in the discovery response section. The authentication information is as follows:

  • wsse: Security: The enrollment client implements the element defined in [WSS] section 5.The The element must be a child of the element.
  • wsse: BinarySecurityToken: The enrollment client implements the element defined in [WSS] section 6.3 The element must be included as a child of the element in the SOAP header.

As described in the Discovery Response section, the inclusion of the wsse: BinarySecurityToken element is opaque to the registration client, and the client does not interpret the string, and inclusion of the element is agreed by the security token authentication server (as in the <> element is opaque to the enrollment client, and the client does not interpret the string, and the inclusion of the element is agreed upon by the security token authentication server (as identified in the element of and the enterprise server.

The element contains a base64-encoded string. The element contains a base64-encoded string. The registration client uses the security token received from the authentication server and base64-encodes the token to identify the The enrollment client uses the security token received from the authentication server and base64-encodes the token to populate the element.wsse: BinarySecurityToken / attributes / ValueType: Das ValueType attribute must be "http: /schemas.microsoft.com/5.0.0.0/ConfigurationManager/Enrollment/DeviceEnrollmentUserToken" wsse: BinarySecurityToken / attributes / ValueType: The ValueType attribute must be "http: / /schemas.microsoft.com/5.0.0.0/ConfigurationManager/Enrollment/DeviceEnrollmentUserToken ".

wsse: BinarySecurityToken / attributes / EncodingType: The EncodingType attribute must be "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd \ # base64binary "sein.wsse: BinarySecurityToken / attributes / EncodingType: The EncodingType attribute must be" http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity -secext-1.0.xsd # base64binary ".

The following is an enrollment policy request example with a received security token as client credential.

After the user is authenticated, the web service retrieves the certificate template that the user should enroll with and creates A sample of the response can be found on MSDN.

MS-XCEP supports very flexible enrollment policies using various Complex Types and Attributes. For # A0 we initially support the minimalKeyLength, the hashAlgorithmOIDReference guidelines and the CryptoProvider.For Windows device, we will first support the minimalKeyLength, the hashAlgorithmOIDReference policies, and the CryptoProviders.The hashAlgorithmOIDReference has OID and OIDReferenceID and policySchema in the GetPolicesResponse.The hashAlgorithmOIDReference has related OID and OIDReferenceID refers to the policyReschema refers to the certificate template version.Version 3 of MS-XCEP supports hashing algorithms.

Note

The Transfer-Encoding may specify Transfer-Encoding Chunked. it must be sent as a message. The HTTP server response must not set Transfer-Encoding to Chunked; it must be sent as one message.

The following snippet shows the policy web service response.

Enrollment web service

This web service implements the MS-WSTEP protocol.It processes the RequestSecurityToken (RST) message from the client, authenticates the client, requests the certificate from the certification authority and returns it in the RequestSecurityTokenResponse ( RSTR) to the client. It processes the RequestSecurityToken (RST) message from the client, authenticates the client, requests the certificate from the CA, and returns it in the RequestSecurityTokenResponse (RSTR) to the client. In addition to the issued certificate contains the response Besides the issued certificate, the response also contains configurations needed to provision the DM client.

The RequestSecurityToken (RST) must have the user credential and a certificate request. The user credentials in an RST SOAP envelope are the same as those in GetPolicies and can vary depending on whether The user credential in an RST SOAP envelope is the same as in GetPolicies, and can vary depending on whether the authentication policy is OnPremise or Federated.BinarySecurityToken in an # A0 contains a Base64-encoded PKCS # 10- The BinarySecurityToken in an RST SOAP body contains a Base64-encoded PKCS # 10 certificate request, which is generated by the client based on the enrollment policy. The client would have a registration policy using MS -XCEP can request a certificate before using The client could have requested an enrollment policy by using MS-XCEP before requesting a certificate using MS-WSTEP. If the PKCS # 10 certificate request is accepted by the certification authority (key length, hash algorithm and so on correspond to the certificate template) If the PKCS # 10 certificate request is accepted by the certification authority (CA) (the key length, hashing algorithm, and so on match the certificate template), the client can enroll successfully.

Note that the requestSecurityToken uses a custom TokenType (http: /schemas.microsoft.com/5.0.0.0/ConfigurationManager/Enrollment/DeviceEnrollmentToken) because our registration token is more than an X.509 v3 certificate a custom TokenType (http://schemas.microsoft.com/5.0.0.0/ConfigurationManager/Enrollment/DeviceEnrollmentToken), because our enrollment token is more than an X.509 v3 certificate. See the Answer section for more details , see the Response section.

The RST can also specify a number of AdditionalContext elements, e.g. The RST may also specify a number of AdditionalContext items, such as DeviceType and Version. Based on these values, for example, the web service can return device-specific and version-specific DM configuration can return device-specific and version-specific DM configuration.

Note

The policy service and the registration service must reside on the same server. That is, they must have the same hostname. The policy service and the enrollment service must be on the same server; that is, they must have the same host name.

The following example shows the enrollment web service request for federated authentication.

After the request is validated, the web service finds the assigned certificate template for the client, updates it if necessary, sends the PKCS # 10 requests to the certification authority, processes the response from the certification authority, creates and outputs an OMA client deployment XML format in the RequestSecurityTokenResponse (RSTR). After validating the request, the web service looks up the assigned certificate template for the client, update it if needed, sends the PKCS # 10 requests to the CA, processes the response from the CA, constructs an OMA Client Provisioning XML format, and returns it in the RequestSecurityTokenResponse (RSTR).

Note

The Transfer-Encoding may specify Transfer-Encoding Chunked. it must be sent as a message. The HTTP server response must not set Transfer-Encoding to Chunked; it must be sent as one message.

Similar to the TokenType in the RST, RSTR uses a custom ValueType in the BinarySecurityToken (http: /schemas.microsoft.com/ConfigurationManager/Enrollment/DeviceEnrollmentProvisionDoc) because the token is more than an X.509 v3 certificate the RST, the RSTR will use a custom ValueType in the BinarySecurityToken (http://schemas.microsoft.com/ConfigurationManager/Enrollment/DeviceEnrollmentProvisionDoc), because the token is more than an X.509 v3 certificate.

The provisioning XML contains:

  • The requested certificates (required)
  • The DM client configuration (required)

The client will install the client certificate, the enterprise root certificate, and intermediate CA certificate if there is one.The DM configuration includes the The DM configuration includes the name and address of the DM server, which client certificate to use, and schedules when the DM client calls back to the server.

Enrollment provisioning XML should contain a maximum of one root certificate and one intermediate CA certificate that is needed to chain up the MDM client certificate Additional root and intermediate CA certificates could be provisioned during an OMA DM session.

When provisioning root and intermediate CA certificates, the supported CSP node path is: CertificateStore / Root / System for root certificate provisioning, CertificateStore / My / User for intermediate CA certificate provisioning.

Here is a sample RSTR message and a sample of OMA client provisioning XML within RSTR. For more information about the configuration service providers (CSPs) used in provisioning XML, see the Enterprise settings, policies and app management section.

The following example shows the enrollment web service response.

The following code shows sample provisioning XML (presented in the preceding package as a security token):

Notes

  • <> # A0 and and elements in the w7 APPLICATION CSP XML are case sensitive and must be all uppercase.
  • In w7 APPLICATION characteristic, both CLIENT and APPSRV credentials should be provided in XML.
  • Detailed descriptions of these settings are located in the Enterprise settings, policies and app management section of this document.
  • The PrivateKeyContainer property is required and must be present in the registration deployment XML through the registry PrivateKeyContainer characteristic is required and must be present in the Enrollment provisioning XML by the enrollment. Other important settings are the Parameter elements PROVIDER-ID,SURNAMEand ADDR, which must contain the unique ID and NAME of your DM provider and the address where the device can connect for configuration deployment PROVIDER ID, SURNAME, and ADDR parameter elements, which need to contain the unique ID and NAME of your DM provider and the address where the device can connect for configuration provisioning.Id and NAME can be any values, but they must be unique. The ID and NAME can be arbitrary values , but they must be unique.
  • Also important is SSLCLIENTCERTSEARCHCRITERIA, which is used for selecting the certificate to be used for client authentication. Search is based on the subject attribute of the signed user certificate. The search is based on the subject attribute of the signed user certificate.
  • CertificateStore / WSTEP enables certificate renewal. If the server does not support it, do not set it.