GetInfo

Short Description

Retrieves identity information, depending on the value in the INFOTYPE parameter, including the origin of a specified user's privileges, the value of active enterprise policies, and so on.

Category

Generalized authorization methods

Interface Version

ISecurity 1.1

Syntax

GetInfo("infoType",credHandle,options,output);

Parameters

Method Parameters
Parameters
Type
Direction
Description
infoType
string
in
Specifies the identity information to get. Valid values are:
  • GetIdentityInfo
  • EnterprisePolicies
  • SASPW_Alias
credHandle
string
in
A string that identifies the user identity for which information is requested. Valid values are:
  • A credential handle obtained by calling the GetCredentials method.
  • An empty string.
  • When INFOTYPE is "GetIdentityInfo", a valid URN for an identity or simply IdentityType:Name. In IdentityType:Name, IdentityType is Person, IdentityGroup, or Role. Name is the Name attribute value of the identity.
options
string array
in
Options submitted in a two-dimensional string array. Options are specific to the INFOTYPE value. The first column in the array must contain an option keyword. The second column contains the keyword value, if there is one. See the “Details” section for information about valid option values.
output
string array
out
A two-dimensional string array containing the output for the requested INFOTYPE. The first column has the name of the attribute whose value is being returned in the second column. See the “Details” section for information about the output for each INFOTYPE.

Details

CREDHANDLE Options

If CREDHANDLE is an empty string, then “INFOTYPE” requests information for the connected user. If CREDHANDLE is a credential handle and the connected user is a trusted user, or it is a URN-like or IdentityType: Name identifier, then information is returned for the specified identity. For information about the format of a URN, see Identifying Resources to ISecurity Methods. When an identifier other than a credential handle is used, the connected user does not have to be a trusted user. However, they must be granted ReadMetadata permission on the identity’s metadata object.
The IdentityType:Name form enables clients to obtain identity information when a credential cannot be obtained. This can happen because the associated login is not known or is not available in a particular scenario. An example of this type of scenario is when a client needs to determine whether an identity has extended privileges as a result of membership in the Unrestricted, User Administrator, or Operator roles, but has no way to authenticate the identity using any of the identity's logins.
The following are examples of how the IdentityType:Name form is used:
'Person:Jane'
'IdentityGroup:AccountingDept'
'Role:AccountsPayableClerks'

INFOTYPE=“GetIdentityInfo” Options and Outputs

The “GetIdentityInfo” value supports the following option keywords:
ReturnUnrestrictedSource
Returns an additional row in the output array if the specified user is an unrestricted user. Otherwise, an additional row is not returned. When a row is returned, the valid values are the following:
Role
Indicates the user identity is a member of the SAS Metadata Server: Unrestricted role.
ConfigFile
Indicates the user has a login user ID that matches a *user ID entry in the adminUsers.txt file.
Role, ConfigFile
Indicates the user is unrestricted from both the Role and ConfigFile sources.
UserClass
Returns one or more of the following values that describe the source of the identity's privileges. When Unrestricted is returned, all of the privileges of Administrator and Operator are assumed. The privileges of Trusted are not assumed.
Unrestricted
Indicates the privilege comes from a *user ID entry in the adminUsers.txt file, or from a metadata identity that has membership in the SAS Metadata Server: Unrestricted role.
Administrator
Indicates the privilege comes from a user ID entry in the adminUsers.txt file that does not have an asterisk.
IdentityAdmin
Indicates the privilege comes from a metadata identity that has membership in the SAS Metadata Server: User and Group Administrators role.
Operator
Indicates the privilege comes from a metadata identity that has membership in the SAS Metadata Server: Operator role.
Normal
Indicates the user does not have any special privileges.
Trusted
Indicates the privilege comes from a user ID entry in the trustedUsers.txt file.
AuthenticatedUserid
Returns the domain-qualified user ID used to make the connection to the SAS Metadata Server, or the domain-qualified user ID corresponding to the specified CREDHANDLE.
IdentityName
Returns the Name attribute value of the Person or IdentityGroup object that corresponds to the authenticated user ID.
IdentityType
Returns Person or IdentityGroup.
IdentityObjectID
Returns the 17–character metadata object identifier of the specified identity.
UnrestrictedSource
Valid values are Role, ConfigFile, or 'Role, ConfigFile'.

INFOTYPE=“EnterprisePolicies” Options and Outputs

The “EnterprisePolicies” value requests enterprise policies. It supports the following option keywords:
ALL
Specifies to return all enterprise policies and their values.
SASSEC_LOCAL_PW_SAVE
Specifies to return the value of the SASSEC_LOCAL_PW_SAVE server configuration option. This server configuration option specifies whether users can create a local copy of the user ID and password that they submit when they log on to a SAS desktop application. A value of 0 indicates Yes. A value of 1 indicates No.

INFOTYPE=“SASPW_Alias” Output

The “SASPW_Alias” value has no option keywords. It returns the AuthenticationDomain alias of the SASPassword authentication provider. The default value is saspw. However, if the AUTHPROVIDERDOMAIN start-up option is used to specify a different alias, then this INFOTYPE value returns the alias.

Exceptions Thrown

The SAS Open Metadata Interface explicitly returns the following exceptions for the GetInfo method:
  • InvalidCredHandle
  • InvalidInfoType
  • InvalidOptionName
  • InvalidOptionValue

Examples

The following is a Java example of a GetInfo method call. The method is issued twice. The first time it is issued, it gets identity information for the connected user. The second time, it gets identity information for a credentialed user. The example includes code that formats and prints the information returned by the two requests:
	public void getInfo() throws Exception  {
		try
		{
            // Defines the GetIdentityInfo “ReturnUnrestrictedSource” option.
			final String[][] options ={{"ReturnUnrestrictedSource",""}};

			System.out.println(""); // Skip a line
			System.out.println("<<<< Begin getInfo() >>>>" );

			// Defines a stringholder for the info output parameter.
            VariableArray2dOfStringHolder info = new VariableArray2dOfStringHolder();

			// Issues the GetInfo method for the current iSecurity connection user.
			iSecurity.GetInfo("GetIdentityInfo","", options, info);
			String[][] returnArray = info.value;

			System.out.println();
            // Specifies a title for the output.
			System.out.println("<<<<<< getInfo() for ISecurity Connection User >>>>>>");
			System.out.println("credHandle=''");
			for (int i=0; i< returnArray.length; i++ )
			{
				System.out.println(returnArray[i][0] + "=" + returnArray[i][1]);
			}
            // Defines a stringholder for the credential handle.
			StringHolder credHandle = new StringHolder();

			// Issues the GetCredentials method.
            iSecurity.GetCredentials(testUserId, credHandle);
			// Issues the GetInfo method for the credentialed user
			iSecurity.GetInfo("GetIdentityInfo",credHandle.value, options, info);
			returnArray = info.value;

			System.out.println(); 
            // Skip one line
            // Specifies a title to print in the output.
			System.out.println("<<<<<< getInfo() for Credentialed User >>>>>>");
			System.out.println("credHandle=" + credHandle.value);
			for (int i=0; i< returnArray.length; i++ )
			{
				System.out.println(returnArray[i][0] + "=" + returnArray[i][1]);
			}

			// Issues the FreeCredentials method.
            iSecurity.FreeCredentials(credHandle.value);

			System.out.println(""); 
                   // Skip a line
			System.out.println("<<<< End getInfo() >>>>" );
		}
		// The following code catches the method's exceptions.
    catch (Exception e) {
			System.out.println("GetInfo: Exceptions");
			e.printStackTrace();
			throw e;
		}

	}
Here is the output from the requests:
<<<< Begin getInfo() >>>>

<<<<<< getInfo() for ISecurity Connection User >>>>>>
credHandle=''
UserClass=Unrestricted, Trusted
AuthenticatedUserid=TESTUSR7@CARYNT
IdentityName=PUBLIC
IdentityType=IdentityGroup
IdentityObjectID=A5CY5BIY.A3000002
UnrestrictedSource=ConfigFile

<<<<<< getInfo() for Credentialed User >>>>>>
credHandle=2d91581c00000000
UserClass=IdentityAdmin
AuthenticatedUserid=TESTUSER@SASPW
IdentityName=testUser
IdentityType=Person
IdentityObjectID=A5CY5BIY.AN000003

<<<< End getInfo() >>>>

Related Methods