Configuring Cognos 8 to Use Cognos Series 7 Namespace

Configuring Cognos 8 to Use Cognos Series 7 Namespace

You can configure Cognos 8 components to use a Cognos Series 7 namespace as the authentication provider. Users will be authenticated based on the authentication and signon configuration of the Cognos Series 7 namespace.

A Cognos Series 7 namespace is required if you want to use Cognos Series 7 PowerCubes and Transformer models in Cognos 8. The namespace must be configured before you load the Transformer models.

If you want to configure a Cognos Series 7 namespace as your authentication source, you must install Content Manager on a computer that supports Cognos Series 7.

Note: You cannot use a Cognos Series 7 Local Authentication Export (LAE) file for authentication with Cognos 8 components.

You can configure Cognos 8 components to use multiple Cognos Series 7 authentication providers. We recommend that all Cognos Series 7 namespaces use the same primary Cognos Series 7 Ticket Server. Otherwise, you may receive errors or be prompted for authentication more than once.

If you change the configuration information stored in the directory server used for Cognos Series 7, you must restart the Cognos 8 service before the changes take effect in the Cognos installation.

A user must be in at least one Access Manager user class to be able to log on to Cognos 8 components.

To use a Cognos Series 7 namespace and to set up single signon, do the following:

	Configure Cognos 8 to use a Cognos Series 7 namespace
	Enable secure communication to the directory server used by the Cognos Series 7 namespace, if required
	Enable single signon between Cognos Series 7 and Cognos 8

Configure a Cognos Series 7 Namespace

You can configure Cognos 8 to use one or more Cognos Series 7 namespaces for authentication.

Steps

On every computer where you installed Content Manager, open Cognos Configuration.
In the Explorer window, under Security, right-click Authentication, and then click New resource, Namespace.
In the Name box, type a name for your authentication namespace.
In the Type list, click the appropriate namespace and then click OK.
The new authentication provider resource appears in the Explorer window, under the Authentication component.
In the Properties window, for the Namespace ID property, specify a unique identifier for the namespace.
Specify the values for all other required properties to ensure that Cognos 8 components can locate and use your existing authentication provider.
If your Series 7 namespace version is 16.0, ensure that the Data encoding property is set to UTF-8. In addition, the computers where Content Manager is installed must use the same locale as the data in the Series 7 namespace.
The host value can be a computer name or an IP address. If you are publishing from PowerPlay Enterprise Server to Cognos 8, you must use the same value format that is used in Cognos Series 7 Configuration Manager for the location of the directory server. For example, if the computer name is used in Cognos Series 7 Configuration Manager, the computer name must also be used in Cognos Configuration for Cognos 8.
If your namespace environment includes version 15.2 of the Series 7 namespace, you must disable the Series7NamespacesAreUnicode setting.
In the Properties window, under Cookie settings, ensure that the Path, Domain, and Secure flag enabled properties match the settings configured for Cognos Series 7.
From the File menu, click Save.
Test the connection to a new namespace. In the Explorer window, under Authentication, right-click the new authentication resource and click Test.

Enabling Secure Communication to the Directory Server Used by the Series 7 Namespace

If you are using an SSL connection to the Directory Server used by the Cognos Series 7 namespace, you must copy the certificate from the Directory Server to each Content Manager computer.

For more information, see the Cognos Access Manager Administrator Guide and the documentation for your Directory Server.

Enabling Single Signon Between Cognos Series 7 and Cognos 8

If your Cognos Series 7 namespace has been configured for integration with your external authentication mechanisms for single signon, the Cognos Series 7 provider will automatically use this configuration.

By configuring single signon, you are not prompted to reenter authentication information when accessing Cognos content that is secured by the Cognos Series 7 namespace.

Steps

Ensure that you configured Cognos 8 components to use a Cognos Series 7 namespace as an authentication provider .
For Cognos Series 7, start Configuration Manager.
Click Open the current configuration.
On the Components tab, in the Explorer window, expand Services, Access Manager - Runtime and click Cookie Settings.
In the Properties window, ensure that the Path, Domain, and Secure Flag Enabled properties match the settings configured for Cognos 8.
Save and close Configuration Manager.
If the Cognos Series 7 namespace uses the Trusted Signon plug-in for single signon, you must now define the SaferAPIGetTrustedSignonWithEnv function.

You can now add Cognos Upfront Series 7 NewsBoxes to your Cognos Connection portal pages.

Cognos Series 7 Namespaces and the Cognos Series 7 Trusted Signon Plug-in

If the Cognos Series 7 namespace uses the Trusted Signon plug-in for single signon, you must define the SaferAPIGetTrustedSignonWithEnv function in your plug-in. Then you must recompile and redeploy the library for single signon to be achieved between Cognos 8 components and your authentication mechanism.

The SaferAPIGetTrustedSignonWithEnv function is an updated version of the SaferAPIGetTrustedSignon function. This update is required because Cognos 8 logon is not performed at the Web server as is the case for Cognos Series 7 applications. Therefore, it is not possible for the plug-in to perform a getenv() API call to retrieve Web server environment variables. The plug-in can request that specific environment variables be removed from the Web server using the SaferAPIGetTrustedSignonWithEnv function.

If you are running both Cognos Series 7 and Cognos 8 products using the same plug-in, both the SaferAPIGetTrustedSignonWithEnv and SaferAPIGetTrustedSignon functions are required. For information about the SaferAPIGetTrustedSignon function, see the Cognos Series 7 documentation.

SaferAPIGetTrustedSignonWithEnv Function

For users to be successfully authenticated by Access Manager, OS signons must exist and be enabled in the current namespace.

The memory for the returned trustedSignonName and trustedDomainName is allocated internally in this API. If the function returns SAFER_SUCCESS, Access Manager calls SaferAPIFreeTrustedSignon to free the memory allocated.

The memory for the returned reqEnvVarList is allocated internally in this API. If the function returns SAFER_INFO_REQUIRED, Access Manager calls SaferAPIFreeBuffer() to free the memory allocated.

Both functions, SaferAPIGetTrustedSignon and SaferAPIFreeBuffer must be implemented to successfully register the library when SaferAPIGetTrustedSignonWithEnv is implemented. The function SaferAPIGetError is required only if you want specific error messages returned from your plug-in.

Syntax

SaferAPIGetTrustedSignonWithEnv(

EnvVar	envVar[],	/[IN]/
char	**reqEnvVarList,	/[OUT]/
void	**trustedSignonName,	/[OUT]/
unsigned long	*trustedSignonNameLength,	/[OUT]/
void	**trustedDomainName,	/[OUT]/
unsigned long	*trustedDomainNameLength,	/[OUT]/
SAFER_USER_TYPE	*userType,	/[OUT]/
void	**implementerData);	/[IN/OUT]/

Parameter	Description
[in] envVar	An array of environment variable names and values that were retrieved from the Web server. The end of the array is represented by an entry with a null envVarName and a null envVarValue. Note that the first time this API is called, the envVar array contains only the end of array marker.
[in] reqEnvVarList	A string that contains a comma separated list of environment variable names that are requested by the Safer implementation. The end of the list must be null-terminated.
[out] trustedSignonName	A sequence of bytes that identifies the currently authenticated user. This value does not need to be null-terminated. This value is mandatory.
[out] trustedSignonNameLength	An integer value that indicates the length of the trustedSignonName. This length should exclude the null terminator, if there is one. This value is mandatory.
[out] trustedDomainName	A sequence of bytes that identifies the domain of the currently authenticated user. This value does not need to be null-terminated. If there is no trustedDomainName, the return is null. This value is optional.
[out] trustedDomainNameLength	An integer value that indicates the length of the trustedDomainName. This length should exclude the null terminator, if there is one. This value is mandatory and must be set to zero if there is no trustedDomainName.
[out] userType	A value that indicates the type of user that Access Manager will authenticate. This value is mandatory. The following return values are required for users to be successfully authenticated by Access Manager: SAFER_NORMAL_USER A named user. OS signons must exist and be enabled in the current namespace. SAFER_GUEST_USER A guest user. A guest user account must exist and be enabled in the current namespace. SAFER_ANONYMOUS_USER An anonymous user. An anonymous user account must exist and be enabled in the current namespace.
[in/out] implementerData	A pointer used to preserve implementation-specific data between invocations. An invocation occurs every time Access Manager calls the trusted signon plug-in. This value is valid only if the trusted signon plug-in was invoked and you set a value for it.