There are two flows for identity mapping today, one for establishing your users PRINCIPAL and the other for creating links to that PRINCIPAL. In the end you end up with PRINCIPAL and then SUBJECT to PRINCIPAL relationships.
Terms discussed.
Host Network . The network the user starts from.
Deployed Network. The network where the application is really deployed.
Auth Network. The network you are linking to and the user will need to authenticate against.
Flow for initial Principal Creation
1. The application calls requireNetworkLogin, telling the client to check if the current user is mapped. This redirects to the deployed networks MAP.php, or a specific map.php for the host network.
2. Map.php gives the user the choice to map the network or create a new principal, we will follow the latter for this walk through.
3. The users selects newprofile and is redirected to trust.php?method=newprofile&....
4. If the newprofile fails, the users gets an error message, else the user seamlessly redirected to a calculated next.
Flow for Mapping Identities
1. The application calls requireNetworkLogin, telling the client to check if the current user is mapped. This redirects to the deployed networks MAP.php, or a specific map.php for the host network.
2. Map.php gives the user the choice to map the network or create a new principal, we will follow the former for this walk through.
3. On the redirect from Map.php to bindmap, bindmap will determine information about the network the user wants to link to. It will construct a login.php request to authenticate the user against a thirdparty network. The user is seamlessly redirected to the thirdparty's network login.
4. The third party authenticated the user and will redirect them to trust.php?method=finalizemap&....
5. At this point finalizemap needs to determine if the authentication was valid and what the users id is on the authenticating network. This is made via an API call to the authenticating network.
6. At this point process is complete and finalizemap can construct the $next which to redirect the user to, hopefully back to the application!
Understanding how $next is constructed
Currently the final url can be one of two locations
Postmap_url + $next: The host network can configured inside of the deployed network where final mapping requests should go to. This is configured per known hosted network. If the initial request to map included &network&next=XXX then the final destination for map will be
postmap_url for the host network (pulled from database) + value of next in request (ie XXX frrom above)
Application: If the &network is not set the final destination will be the canvas_url for the application on the host network, followed by the next request from the parameters.
canvas_url + value of next in request
