Log in using HTTP header authentication

NOTE

The instructions in this section apply only to Enterprise Server.

Your application can use a trusted central server to authenticate users with single sign-on and pass your network's (here called external) authentication to Enterprise Server, without explicitly passing an Enterprise Server user ID and password. (For detailed instructions on how to set up and configure HTTP header authentication, see Adobe Connect Enterprise Installation and Configuration Guide).

With HTTP header authentication, a user logs in to your authentication server. Once the user is authenticated, you add an HTTP request header that identifies the user, or configure a proxy server to add the header. The authentication filter on Connect Enterprise (named HeaderAuthenticationFilter) converts your user identifier to a Connect Enterprise login ID and authenticates the user.

Authentication filters convert external authentication credentials to Enterprise Server credentials.

External authentication works in addition to standard Connect Enterprise authentication. Each user who needs to access Enterprise Server needs a valid Enterprise Server login and password.

When you send a login request to Enterprise Server with an external authentication credential:

The authentication filter intercepts the request and checks for a user on Enterprise Server with an ext-login field that matches your external credential.
If a match exists, the filter passes your external authentication to Enterprise Server, and the server logs the user in.
If no match exists, the filter passes the login request to the server, which displays its login page. The user must then log in to Enterprise Server.
If the user logs in successfully, Enterprise Server updates the ext-login field in the user's profile with the external credential from your request. The next time you send a request with the user's external credential, Enterprise Server finds a match in ext-login, and the user does not need to log in to Connect Enterprise.
If the user does not log in successfully, the user is not allowed access to Enterprise Server applications, content, or meetings.

The steps that follow describe how to call login when you use HTTP header authentication.

Log in to Enterprise Server using HTTP header authentication

Configure your network servers and Enterprise Server for HTTP header authentication using the instructions in Connect Enterprise Installation and Configuration Guide.

In [your server directory]/appserv/conf/WEB-INF/web.xml, remove comment tags around the filter-mapping element for HeaderAuthenticationFilter and add comment tags around any other filter-mapping elements:

<filter-mapping>
    <filter-name>HeaderAuthenticationFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>
<!--
<filter-mapping>
    <filter-name>NtlmAuthenticationFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>
-->

In the filter element for HeaderAuthenticationFilter, enable the /api/ pattern for request URLs. You have two choices for how to do this.

If your application uses the XML API and any Connect Enterprise applications In the filter element for HeaderAuthenticationFilter, use comment tags to disable the init-param element with a param-value of /api/:

<!--
<init-param>
    <param-name>ignore-pattern-0</param-name>
    <param-value>/api/</param-value>
</init-param>
-->

If your application uses only the XML API Change the filter-mapping element for your filter type to use the URL pattern /api/* instead of /*:

<filter-mapping>
    <filter-name>HeaderAuthenticationFilter</filter-name>
    <url-pattern>/api/*</url-pattern>
</filter-mapping>

Then, in the filter element for your filter type, add comment tags around all init-param elements with a param-name of ignore-pattern-x:

<filter>
    <filter-name>HeaderAuthenticationFilter</filter-name>
    <filter-class>
            com.macromedia.airspeed.servlet.filter.HeaderAuthenticationFilter
        </filter-class>
<!--
    <init-param>
        <param-name>ignore-pattern-0</param-name>
        <param-value>/api/</param-value>
    </init-param>
    ...
    <init-param>
        <param-name>ignore-pattern-4</param-name> 
        <param-value>/servlet/testbuilder</param-value> 
    </init-param>
-->
</filter>

Configure Enterprise Server so that users are created with the field ext-login set to the external user ID you send (see Connect Enterprise Installation and Configuration Guide for details).
By default, ext-login has the same value as login, the Enterprise Server login ID.
Once your system authenticates the user, create a login request. Add the parameter external-auth=use, but no login or password parameters:
```
https://example.com/api/xml?action=login&external-auth=use
```
Add your authenticated user ID to the HTTP request header. By default, use the header name x-user-id:
```
x-user-id: joesmith
```
You can specify a different header name by setting a value for HTTP_AUTH_HEADER in the custom.ini file. You can also configure a proxy server to set the HTTP header value. See Connect Enterprise Installation and Configuration Guide for details of either.
Parse the response for a status code of ok.
Handle the BREEZESESSION cookie value returned in the response header. You have two choices for how to do this.
If you use a client library that manages cookies Allow your library to extract the cookie value, store it, and pass it back to the server on subsequent requests for the user.

If you manage cookies yourself Extract the value of the BREEZESESSION cookie from the response header. Store it and pass it back to the server in the session parameter of all subsequent actions you call for the same user, as long as the user's session is valid:
```
https://example.com/api/xml?action=principal=list
        &session=breezs7zuepmy9wh2tseu
```
Be sure not to reuse the cookie value when the user's session ends.

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/breeze/6/xml_api/02_logi5.htm