Authentication Web Service

Description	Authentication services
Namespace	http://portwise.com/ws/v1/authentication
Endpoint	https://<hostname>/ws/v1/services/Authentication
Style	Document/Literal
WSDL	https://<host>/ws/v1/services/Authentication?wsdl
Since	5.2
See also	Authorization

Authentication is required before any usage of the XPI services, except authorization which may be used for on-demand authentication, i.e. it will ask for additional authentication if the subject does not have the appropriate authentication level. Once authenticated the subject will be populated with security identities, i.e. principals. It is possible to add own principals to the subject; make sure they do not collide with any reserved principal names. Depending on the configuration it may be necessary to authenticate using more than one method when accessing a resource.

When using PortWise OCRA it is possible to use an application generated challenge, which may or may not be a representation of a text to be signed. When using this mode, the challenge should be sent in the subject, with the key 'challenge', and the generated OTP in the password item. Username, challenge and password are mandatory.

Endpoint Services

Name

authenticate

Description

Authenticates a subject using the specified method.

Input

subject	a Subject representing the entity to be authenticated. The subject must contain the required credentials. Optional. You can specify a prioritized list of notification channels to be used in the authentication. The list is separated with ';'. This will only matter on methods that use notifications, and if not set, the configured default will be used.
method	an integer with the ID of the authentication method to be used. Check the Administrator for authentication method's ID.

Output

The supplied Subject populated with username and session principals, all the credentials will be removed.

Since

5.2

Faults

WSException	if a general error occurs.
AuthenticationException	if authentication failed.
ChallengeException	if additional credentials are required.

Name

logout

Description

Logs out a subject by releasing any pending server resources and removes the authentication principals.

Input

subject

the Subject representing the entity to be logged out.

Output

The supplied Subject with the authentication principals removed.

Since

5.2

Faults

WSException

if a general error occurs.

Java Example

This example shows how to make an authentication call that requires a challenge, error handling omitted.

    // Locate authentication web service
    AuthenticateService locator = new AuthenticateService();
    Authenticate service = locator.getAuthentication();

    // Configure required authentication credentials
    MapItem username = new MapItem();
    username.setKey("username");
    username.setValue("billy".getBytes(StandardCharsets.UTF_8));
    MapItem password = new MapItem();
    password.setKey("password");
    password.setValue("secret".getBytes(StandardCharsets.UTF_8));

    // Optionally, you can send a prioritized list of notification channel
    // display names to use in the authentication. The list is separated with ';'.
    // This will only matter on methods that use notifications, and if not set, the configured default will be used.
    MapItem channels = new MapItem();
    channels.setKey("channels");
    channels.setValue("First SMS Channel 1; Secondary Channel".getBytes(StandardCharsets.UTF_8));

	// Optionally, From 5.13, you can also send a customized message template for sending OTP messages while doing authentication.
    // Currently this is supported only by MobileText Authentication method.
    // If not set, the configured default message will be used.
	// Note: {0} is for OTP , {1} is for validity in seconds , {2} is for time at which OTP was generated and {3} is user requesting authentication
	// These placeholders are fixed for the type of value they will carry, i.e., {0} will always have OTP, etc.
    MapItem msgTemplate = new MapItem();
	msgTemplate.setKey("msgtemplate");
	msgTemplate.setValue("This is a custom message. Your OTP is {0} which is valid for {1} seconds from {2} and is for user {3}".getBytes(StandardCharsets.UTF_8));
    creds.add(msgTemplate);

	// Optionally you can add usermobile.
    MapItem usermobile = new MapItem();
    usermobile.setKey("usermobile");
	usermobile.setValue("User mobile number".getBytes(StandardCharsets.UTF_8));
    creds.add(usermobile);

	// Optionally you can add useremail from 6.1.0
    MapItem useremail = new MapItem();
    useremail.setKey("useremail");
	useremail.setValue("User email Id".getBytes(StandardCharsets.UTF_8));
    creds.add(useremail);

    // Create subject
    Subject subject = new Subject();
    subject.getCredentials().add(username);
    subject.getCredentials().add(password);
    subject.getCredentials().add(channels);
    subject.setLanguage("en");

    try {
        // Execute first authenticate call using authentication method with ID 2
        subject = service.authenticate(subject, 2);
    } catch (ChallengeException ce) {
        String msg = null;
        int passwordIndex = -1;

        // Get returned subject from the challenge exception, it will
        // contain the required parameters for the challenge response
        subject = ce.getFaultInfo().getSubject();
        List<MapItem> creds = subject.getCredentials();

        // Locate parameters "replymsg" and "password"
        for (MapItem item : subject.getCredentials()) {
            if (item.getKey().equals("replymsg")) {
                msg = new String(item.getValue());
            } else if (item.getKey().equals("password")) {
                passwordIndex = creds.indexOf(item);
            }
        }

        // Show message and wait for token input
        ...

        // Update password credential with the token
        creds.get(passwordIndex).setValue("token".getBytes(StandardCharsets.UTF_8));

        // Execute second authenticate call using same authentication method ID
        subject = service.authenticate(subject, 2);

        // If all goes well, the subject is now authenticated
        // Use the returned Subject if you need to make any other calls to XPI:WS
    }

    // Do some other things
    ...

    // Log out
    service.logout(subject);