Manage login sessions of users using APIs

Search

Log in and log out a user and manage their session from a custom application using Adobe Connect Web Service APIs.

Log in from an application

In Adobe Connect there are several ways to accomplish tasks like how to log a user in from your application, make requests, handle responses, and log the user out. The appropriate method depends on your development environment, server configuration, and application design.

Any custom application you write that uses Adobe® Connect™ Web Services functionality or integrates with a third-party system needs to log in a user to Adobe Connect. In its simplest form, the process of logging in calls the login action.

However, the technique for logging in varies according to whether you use cookie management, have a licensed server or a hosted account, and authenticate directly to Adobe Connect or use external authentication. Depending on your environment and server configuration, you might also use combinations of these options.

Cookie management

When a user logs in, Adobe Connect returns a cookie that identifies the user’s session. You need to pass the cookie back to the server on all calls made to the server during the user’s session. Then, when the user logs out, the server makes the cookie expire and you should invalidate it.

In your development environment, you can use a code library that manages cookies for you. The process of logging in and managing a user’s session varies according to whether you use a cookie management library or manage the user’s session yourself.

Licensed server or hosted account

Your organization might have a licensed Adobe Connect server within your firewall, or you may have an Adobe Connect hosted account at Adobe. Either way, you send XML requests over HTTP or HTTPS, but security requirements and the login process vary. If you are a hosted customer, you can use certain parameters with the login action to avoid sending user IDs and passwords over the Internet.

Direct or external authentication

Whether you are a hosted or licensed customer, your application might authenticate directly to Adobe Connect, or you might authenticate users on your own network, set an identifier in an HTTP request header, and send it to Adobe Connect. The login process varies according to whether you use direct or external authentication.

Log in to Adobe Connect server

The standard technique for logging a user in to Adobe Connect server uses the login action, passing the user’s login ID and password. This technique works with both HTTP GET and POST requests.

You also need to manage the BREEZESESSION cookie the server returns for each user session. If you use a client-side cookie management library, it is much easier to allow it to manage cookies for you than to manage the cookies yourself. If you do not have such a library, call login with the session parameter, as it is easier and more reliable than setting HTTP header values.

Note:

If you send user passwords to Adobe Connect server, use SSL so passwords are encrypted in transit, even if you have a licensed Adobe Connect server within your own firewall.

Note:

Log in with cookie management is the recommended method of logging in to Adobe Connect server. Log in using the session parameter method does not work when enhanced security is enabled.

Log in with cookie management (recommended)

  1. Call the login action, passing it the user’s login ID and password, but no session parameter:

     http://example.com/api/xml?action=login&login=bobs@acme.com 
         &password=football

  2. Parse the response for a status code of ok.

    If the login is successful, the server returns the BREEZESESSION cookie in the response header:

     Set-Cookie: BREEZESESSION=breezbryf9ur23mbokzs8;domain=.macromedia.com;path=/

  3. Allow your cookie management library to manage the BREEZESESSION cookie.

    Your client-side library passes the cookie back to the server in a request header on subsequent calls for the remainder of the user’s session. You do not need to set the cookie in the request header explicitly. When the user logs out, the cookie expires.

Log in using the session parameter (not recommended)

This method works when enhanced security is not enabled for an Adobe Connect account. If your account has enhanced security enabled, then use the above method to log in with cookie management.

By default, enhanced security is not enabled for the accounts on the hosted system. If you wish to enable it for your account, go to Administration > More Settings, and check Enable Enhanced Security.

  1. Before you log the user in, call common-info to get the value of the BREEZESESSION cookie:

     http://example.com/api/xml?action=common-info

  2. Extract the cookie value from the response:

     <cookie>breezxq66rt43poai3if8</cookie>

  3. Log the user in, specifying the cookie value:

     http://example.com/api/xml?action=login&login=bobs@acme.com 
         &password=football&session=breezxq66rt43poai3if8

  4. Parse the response for a status code of ok.

  5. Use the session parameter with the same cookie value on subsequent calls for the user, until the user’s session ends:

     https://example.com/api/xml?action=principal-list 
         &session=breezxq66rt43poai3if8

  6. When the user logs out or the user’s session ends, do not reuse the cookie value.

Log in to a Adobe Connect hosted account

If you want to log in directly to an Adobe Connect hosted account or multiple hosted accounts, you still use the login action, but you need to specify an account ID or domain name, in addition to the user’s login ID and password. You can specify a domain name if you want to avoid sending an account ID over the Internet.

With an Adobe Connect hosted account, you cannot use single sign-on or external authentication. You must pass the user’s authentication credentials on the Adobe Connect hosted account, not the credentials for an external network.

Note:

It is important to have SSL enabled on your Adobe Connect hosted account, because you are sending user IDs, passwords, and account information over the Internet to your Adobe Connect account hosted at Adobe.

Log in to an Adobe Connect hosted account with an account ID

  1. Before you log the user in, call common-info with the domain name of your Adobe Connect hosted account in either the request URL or the domain parameter:

     http://acme.adobe.com/api/xml?action=common-info 
 http://adobe.com/api/xml?action=common-info&domain=acme.adobe.com

  2. Parse the response for the values of cookie and account-id:

     <cookie>Sbreezzd2dfr2ua5gscogv</cookie>  
 ... 
 <account account-id="295153" />

  3. Collect the user’s login ID and password in your application.

  4. Call the login action, adding the user’s credentials and the account-id and session parameters: 

     https://example.com/api/xml?action=login&login=joy@acme.com 
     &password=happy&account-id=295153&session=Sbreezzd2dfr2ua5gscogv

  5. Parse the response for a status code of ok.

  6. (Optional) If you prefer, you can call login before common-info, extract the cookie value from the response header, and manage it yourself or using a cookie management library.

Log in to an Adobe Connect hosted account with a domain name

  1. Before you log the user in, call common-info with the domain name of your Adobe Connect hosted account in either the request URL or the domain parameter:

     http://acme.adobe.com/api/xml?action=common-info 
 http://adobe.com/api/xml?action=common-info&domain=acme.adobe.com

  2. Parse the response for the values of cookie and host:

     <cookie>breezxq66rt43poai3if8</cookie> 
 ... 
 <host>https://acme.adobe.com</host>

  3. Extract the domain name from the value of host:

     acme.adobe.com

  4. In your application, collect the user’s login ID and password.

    Be sure the login ID is the user’s Adobe Connect hosted account login ID, not an external one.

  5. Call login, adding the user’s credentials and the domain and session parameters:

     https://example.com/api/xml?action=login&login=joe 
     &password=smith99&domain=acme.adobe.com&session=breezxq66rt43poai3if8

    The domain is equivalent to the account-id, but by using it you can avoid sending an account ID over the Internet, especially if you use a non-encrypted connection.

  6. Parse the response for a status code of ok.

  7. (Optional) If you prefer, you can call login before common-info, extract the cookie value from the response header, and manage it yourself or using a cookie management code library.

Log in using HTTP header authentication

Note:

The instructions in this section apply only to Adobe Connect 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 Adobe Connect server, without explicitly passing an Adobe Connect server user ID and password. (For detailed instructions on how to set up and configure HTTP header authentication, see Adobe Connect 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 Adobe Connect (named HeaderAuthenticationFilter) converts your user identifier to an Adobe Connect login ID and authenticates the user.

Authentication filters convert external authentication credentials to Adobe Connect credentials.
Authentication filters convert external authentication credentials to Adobe Connect credentials.

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

When you send a login request to Adobe Connect server with an external authentication credential:

  • The authentication filter intercepts the request and checks for a user on Adobe Connect server with an ext-login field that matches your external credential.

  • If a match exists, the filter passes your external authentication to Adobe Connect 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 Adobe Connect server.

  • If the user logs in successfully, Adobe Connect 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, Adobe Connect server finds a match in ext-login, and the user does not need to log in to Adobe Connect.

  • If the user does not log in successfully, the user is not allowed access to Adobe Connect server applications, content, or meetings.

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

Log in to Adobe Connect server using HTTP header authentication

  1. Configure your network servers and Adobe Connect server for HTTP header authentication using the instructions in Adobe Connect Installation and Configuration Guide.

  2. 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> 
 -->

  3. 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 Adobe Connect 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>

  4. Configure Adobe Connect server so that users are created with the field ext-login set to the external user ID you send (see Adobe Connect Installation and Configuration Guide for details).

    By default, ext-login has the same value as login, the Adobe Connect server login ID.

  5. 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

  6. 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 Adobe Connect Installation and Configuration Guide for details of either.

  7. Parse the response for a status code of ok.

  8. 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 a request in an XML document

At times, you may prefer to send an HTTP POST request to the server to make sure the data is secure and not visible in transit. In that case, specify the action name and parameters in an XML document.

Make an XML document request

  1. Create an XML document with the root element params and param child elements for the action name and each parameter:

     <params> 
     <param name="action">login</param> 
     <param name="login">jon@doe.com</param> 
     <param name="password">foobar</param> 
 </params>

    • You can only send one action in the params root element. You cannot batch multiple actions to be executed sequentially.

    • The XML document you send must be valid and well-formed. Try validating the document in an XML editor before you send it.

  2. Write code that sends an HTTP POST request to Adobe Connect and receives an XML response.

    The specific code will vary according to your programming language and development environment.

  3. In your code, send the XML document to Adobe Connect in the body of the HTTP POST request.

    • Read the XML document into the request.

    • Be sure to set a content-type header of text/xml or application/xml.

Parse a response with XPath

When you receive an XML response from Adobe Connect, you need to be able to parse it to extract the XML elements you need.

If you are working in a language such as Java™, with an XML parser (such as Xerces or JDOM) installed, you can parse through an XML response, select values from nodes, and then use those values.

Use XPath to parse a response

  1. Write a method that calls one or more actions. Create an instance of the XPath class so that you can use the XPath expressions. Call the actions, read the XML response, and use XPath syntax to select the values you need:

     public String scoUrl(String scoId) throws XMLApiException { 
         try { 
             Element e = request("sco-info", "sco-id=" + scoId); 
             if(!(codePath.valueOf(e).equalsIgnoreCase("ok"))) 
                 return ""; 
             XPath xpath = XPath.newInstance("//url-path/text()"); 
             String path = ((Text) xpath.selectSingleNode(e)).getText(); 
  
             e = request("sco-shortcuts", null); 
             xpath = XPath.newInstance("//domain-name/text()"); 
             String url = ((Text) xpath.selectSingleNode(e)).getText(); 
  
             return url + "/" + path.substring(1) + "?session=" + breezesession; 
         } catch (JDOMException jde) { 
             throw new XMLApiException(PARSE_ERROR, jde); 
         } 
 }

    You can also use string pattern matching to check for a status code of ok. A successful action always returns this response:

     <?xml version="1.0" encoding="utf-8" ?>  
 <results> 
     <status code="ok" />  
 </results>

    You can check the response for the pattern ok or code=”ok” .

Parse an error response

When an API action completes successfully, it returns a status code of ok. If the call is not successful, it can also return any of the following status codes:

invalid

Indicates that the call is invalid in some way, usually invalid syntax.

no-access

Shows that the current user does not have permission to call the action, and includes a subcode attribute with more information.

no-data

Indicates that there is no data available for the action to return, when the action would ordinarily return data.

too-much-data

Means that the action should have returned a single result but is actually returning multiple results.

When the status code is invalid, the response also has an invalid element that shows which request parameter is incorrect or missing:

 <?xml version="1.0" encoding="utf-8" ?>  <results>   <status code="invalid">   <invalid field="has-children" type="long" subcode="missing" />   </status>  </results>

When the status code is no-access, the subcode explains why:

 <?xml version="1.0" encoding="utf-8" ?>  <results>   <status code="no-access" subcode="denied" />  </results>

All valid values for code, subcode, and invalid are described in status, in the API reference. Your application needs to read and handle status codes and subcodes.

Handle status codes

  1. Write a method that parses an XML API response for the status code and subcode. This is an example in Java:

     private String getStatus(Element el) throws JDOMException { 
     String code = codePath.valueOf(el); 
     String subcode = subcodePath.valueOf(el); 
     StringBuffer status = new StringBuffer(); 
     if(null != code && code.length() > 0) 
             status.append(code); 
     if(null != subcode && subcode.length() > 0) 
             status.append(" - " + subcode); 
     return status.toString(); 
 }

  2. When you call an action, parse the response for the status.

  3. If the status is not ok, return a null value, display the error status code for debugging, or throw an application exception.

    The action to take depends on which call you are making and how your application is designed.

Log a user out

When a user logs out, the user’s session ends, and Adobe Connect invalidates the BREEZESESSION cookie by setting it to null and using an expiration date that has passed. For example, if you call logout on August 29, 2006, you see this Set-Cookie method in the response header, setting an empty cookie value and an expiration date a year earlier:

 Set-Cookie: BREEZESESSION=;domain=.macromedia.com;expires=Mon, 29-Aug-2005 
     22:26:15 GMT;path=/

If you are managing the BREEZESESSION cookie, invalidate the value so it is not reused after a user logs out.

Log a user out and invalidate the session cookie

  1. Call logout to log the user out:

     https://example.com/api/xml?action=logout

  2. Parse for a status code of ok to make sure the logout was successful.

  3. Set the cookie value to null or otherwise invalidate it. For example, in this Java code snippet, the breezesession variable stores the cookie value and is set to null:

         public void logout() throws XMLApiException { 
         request("logout", null); 
         this.breezesession = null; 
     }
Adobe logo

Sign in to your account

Quick links

View all your plans Manage your plans

Legal Notices    |    Online Privacy Policy