Overview

AGAuthenticationModule represents an authentication module and provides the authentication and enrollment API. The default implementation uses REST as the auth transport. Similar to the Pipe, technical details of the underlying system are not exposed.

Register a user

The enroll function of the AGAuthenticationModule protocol is used to register new users with the backend:

// assemble the dictionary that has all the data for THIS particular user:
NSMutableDictionary* userData = [NSMutableDictionary dictionary];
[userData setValue:@"john" forKey:@"username"];
[userData setValue:@"123" forKey:@"password"];
[userData setValue:@"me@you.com" forKey:@"email"];
[userData setValue:@"21sda812sad24" forKey:@"betaAccountToken"];

// register a new user
[myMod enroll:userData success:^(id data) {
    // after a successful _registration_, we can work
    // with the returned data...
    NSLog(@"We got: %@", data);
} failure:^(NSError *error) {
    // when an error occurs... at least log it to the console..
    NSLog(@"SAVE: An error occured! \n%@", error);
}];

The enroll function submits a generic map object which contains all the information about the new user, that the server endpoint requires. The default (REST) auth module issues for the above, a request against https://todo-aerogear.rhcloud.com/todo-server/auth/enroll. Besides the NSDictionary, the function accepts two simple blocks that are invoked on success or in case of an failure.

Login

Once you have a valid user you can use that information to issue a login against the server, to start accessing protected endpoints:

// issuing a login
[myMod login:@{@"username": @"john", @"password": @"123"} success:^(id object) {
    // after a successful _login_, we can work
    // with the returned data...
} failure:^(NSError *error) {
    // when an error occurs... at least log it to the console..
    NSLog(@"SAVE: An error occured! \n%@", error);
}];

The login function submits a generic map object which contains the credentials that the server login service requires and accepts two simple blocks that are invoked on success or in case of a failure to login.

The default (REST) auth module issues for the above, a request against _https://todo-aerogear.rhcloud.com/todo-server/auth/login

Pass the auth module to a pipe

After running a successful login, you can start using the AGAuthenticationModule object on a AGPipe object to access protected endpoints:

id<AGPipe> tasks = [pipeline pipe:^(id<AGPipeConfig> config) {
    [config setName:@"tasks"];
    [config setBaseURL:serverURL];
    [config setAuthModule:myMod];
}];

[tasks read:^(id responseObject) {
    // LOG the JSON response, returned from the server:
    NSLog(@"READ RESPONSE\n%@", [responseObject description]);
} failure:^(NSError *error) {
    // when an error occurs... at least log it to the console..
    NSLog(@"Read: An error occured! \n%@", error);
}];

When creating a Pipe you need to use the authModule argument in order to pass in an AGAuthenticationModule object.

Logout

The logout from the server can be archived by using the logout function:

// logout:
[myMod logout:^{
    // after a successful _logout_, when can notify the application
} failure:^(NSError *error) {
    // when an error occurs... at least log it to the console..
    NSLog(@"SAVE: An error occured! \n%@", error);
}];

The default (REST) auth module issues for the above a request against https://todo-aerogear.rhcloud.com/todo-server/auth/logout. The function accepts two simple blocks that are invoked on success or in case of an failure.

Time out and Cancel pending operations

As with the case of Pipe, configured timeout interval (in the config object) and cancel operation in AGAuthenticationModule is supported too.