Authentication in Thruway WAMP Router

This is an article about how the Thruway WAMP (Web Application Messaging Protocol) Router works.

This is not necessarily intended to be a how-to article, but a detailed discussion of what the authentication process is and what sequence happens during authentication in the Thruway router.

In order to have a basis for the discussion, it would be beneficial to read the authentication section of the WAMP spec.

As a quick overview, the WAMP authentication process involves the client, upon connecting, sending a HELLO message to the router. This message, along with the realm name and other information, will tell the router what authentication methods it supports, and may also provide other information, such as an auth_id.

Transports can also assist in the authentication by inserting additional details that are transport-specific (addresses, transport-layer credentials, etc.) This information can be forwarded in the HELLO.Options.transport.auth section of the HELLO message.

With this information, the router can decide to send a welcome message to the client – allowing them into the realm, send a challenge message to the client – asking them to authenticate themselves, or can send an abort message.

Upon receiving the challenge message, the client is responsible for responding with an authenticate message appropriate for the selected auth_method. This message is then used by the router to either allow the person in with a welcome message or reject the authentication with an appropriate abort message.

How Thruway handles this:

In Thruway, the Realm object handles the HELLO and AUTHENTICATE messages.

When the Realm receives the HELLO message, it checks to see if its own authenticationManager property is set. If it is not set, it will send a WELCOME, allowing the session to be established. If there is an authenticationManager, then it will call the onAuthenticationMessage method sending the Realm, Session, and HelloMessage to it.

The AuthenticationManager is responsible for evaluating what steps to take next. It will send a message to the client (using the session) to either WELCOME or CHALLENGE the client depending on the auth_method(s) requested. If there is a challenge sent, the AuthenticationManager will receive the AUTHENTICATE message response through the same onAuthenticationMessage method called by the Realm.

When the AuthenticationManager is satisfied with the client’s credentials (which can be as soon as it gets the HELLO or after it gets the AUTHENTICATE), it sends a WELCOME message. The manager needs to call $session->setAuthenticated(true) so that the realm knows it is now authenticated. The manager should also set authentication details on the session object (auth_id, auth_method, etc.).

Thruway’s AuthenticationManager implementation:

Thruway’s implements the AuthenticationManager using a WAMP internal client. This allows any client that can talk WAMP to provide authentication services by exposing RPC calls and then registering itself for a specific realm and auth_method.

An authentication provider (which again, can be any WAMP client that supports RPCs) first registers two RPC calls, one to handle when a HELLO message is received and one to handle when an AUTHENTICATE message is received. For purposed of this discussion, we will refer to them as onhello and onauthenticate RPCs (in reality, any valid, available name can be used for the RPC calls).

Registering the Authentication Method:

Once the RPCs are registered, the provider calls the thruway.auth.registermethod RPC with 3 arguments, the auth_method which is a string, an object with “onhello” and “onauthenticate” properties that identify the actual names of the RPCs that should be called during the authentication process, and an array of realm names. The realm names argument supports “*” as a wildcard for all domains.

The onhello RPC:

The onhello RPC receives 2 argument, the first is the actual HELLO message, the second is an object with some session info (realm and sessionId). This RPC needs to return 1 or 2 arguments. This first argument is a string that is on of “ERROR”, “FAILURE”, or “CHALLENGE”. If “CHALLENGE”, the second argument must contain the challenge details.

If “ERROR” or “FAILURE”, the authentication manager will abort the session.

If “CHALLENGE”, the authentication manager will send a CHALLENGE message back to the authenticating client with the details provided.

The onauthenticate RPC:

The onauthenticate RPC is called with one argument, an object with authmethod, challenge, extra, and signature properties. The authmethod property is the authmethod string, the challenge is the challenge message that was sent to the client after the hello message, extra is an object that has a challenge_details property that is extracted from the AUTHENTICATE message, and signature is the string signature that was sent from the client.

The RPC returns 1 or 2 arguments. The first is the result. “SUCCESS” signifies that the authentication was successful, anything else is a failure.

If “SUCCESS”, the second argument is an object with properties that will be added to the WELCOME message that will get sent to the client.