README

BUILD

1. Install maven version 3.0.3 or later (see how to install maven here:
   http://maven.apache.org/download.html#Installation)
   Use JDK version 6 (not 5)

2. Download the source code from the subversion repository located at:
   https://svn.gluu.info/repository/openxdi/oxAuth

3. Install gluu-core.jar using the command:
   mvn install:install-file -Dfile=gluu-core.jar -DgroupId=org.gluu -DartifactId=gluu-core -Dversion=1.0 -Dpackaging=jar

4. Configure the file Server/src/test/resources/conf/oxauth-ldap.properties

5. Go to Client directory of oxAuth Project and run command: mvn clean install

6. Go to Server directory of oxAuth Project and run command: mvn clean install



DEPLOYMENT

1. Use Tomcat 6.x or later

2. Use JDK version 6 (not 5)

3. Copy and edit the files located at Server/conf to TOMCAT_HOME/conf

4. Copy the file Server/target/oxauth.war to TOMCAT_HOME/webapps


To test the deployment:

1. Edit the file Client/test/resources/testng.xml, change all the test attributes to enabled=“true” and point the URLs
   to your deployment.

2. Go to Client directory of oxAuth Project and run command: mvn test


Testing with SSL and self signed certificate:

1. openssl s_client -connect localhost:8443

2. Cut and paste the certificate (including BEGIN and END lines) into a local file localhost.pem

3. sudo keytool -import -alias localhost -keystore $JAVA_HOME/jre/lib/security/cacerts -file localhost.pem

4. The default keystore password is: changeit


JAVADOC

1. Generate the documentation using the command: mvn javadoc:jar



INTEGRATE oxAuth WITH YOUR SYSTEM

1. Register your Web Application as a client in the file TOMCAT_HOME/conf/oxauth-registration.xml

2. From step 1, make available in your Web Application the following oxAuth registration values:

client-identifier
client-secret
redirection-uri

3. In your web app add a link to the following URL (extra line breaks are for display purposes only):

http://localhost:8080/oxauth/authorize?
response_type=code
&client_id=<your-client-identifier>
&redirect_uri=<your-redirection-uri>
&state=<state>

Where:
- response_type is mandatory and must be set to "code".
- client_id is mandatory and must be set to the value from step 2.
- redirect_uri is mandatory and must be set to the value from step 2.
  It must be URL encoded, for example: https%3A%2F%2Fclient.example.com%2Fcb%3ffoo%3dbar
  To encode it you can use: java.net.URLEncoder.encode(redirectUri, "UTF-8")
- state is optional but recommended to prevent cross-site request forgery.
  It is an opaque value used by the client to maintain state between the request and callback.
  So, you generate a value, send it to oxAuth and the state value returned from oxAuth must be the same you sent.

CODE:
AuthorizationRequest authorizationRequest = new AuthorizationRequest(ResponseType.CODE, clientId);
authorizationRequest.setRedirectUri(redirecturi);
authorizationRequest.setState(state);
String queryString = "http://localhost:8080/oxauth/authorize?" + authorizationRequest.getQueryString();
// Put the queryString in a link or redirect to it.

4. In this step oxAuth will ask the user to login if it is not already logged in, and request its permission.

5. If the user grants permission, oxAuth will redirect to your redirect_uri and send an authorization code as parameter.
   For example (extra line breaks are for display purposes only):

<your-redirection-uri>?
code=<authorization-code>
&state=<state>

If user denies the permission you will receive a response like:

<your-redirection-uri>?
error=access_denied
&error_description=<description-about-the-error>
&state=<state>

6. Use the authorization code you receive in step 5 to request an access token:

CODE:
String credentials = clientIdentifier + ":" + clientSecret;
String tokenUrl = "http://localhost:8080/oxauth/restv1/token";
TokenClient tokenClient = new TokenClient(tokenUrl);
TokenResponse response = tokenClient.execAuthorizationCode(authorizationCode, redirectUri, credentials);
String accessToken = response.getAccessToken();

Where:
- authorizationCode Received in step 5
- redirectUri Your redirect URI
- credentials From step 2 concatenated with a colon in the middle:
  credentials = clientIdentifier + ":" + clientSecret;

7. To extract the information encoded in the accessToken (JWT):

CODE:
JwtToken jwtToken = new JwtToken(accessToken);

jwtToken.getType();
jwtToken.getAlgorithm();
jwtToken.getJsonWebKeyUrl();
jwtToken.getKeyId();
jwtToken.getExpirationTime();
jwtToken.getIssuedAt();
jwtToken.getIssuer();
jwtToken.getUserId();
jwtToken.getAudience();
jwtToken.getOxInum();
jwtToken.getOxOpenIdConnectVersion();

jwtToken.validateSignature(credentials));

8. To validate your accessToken:

CODE:
validateUrl = "localhost:8080/oxauth/restv1/validate";
ValidateTokenClient validateTokenClient = new ValidateTokenClient(validateTokenUrl);
ValidateTokenResponse response = validateTokenClient.execValidateToken(accessToken);

response.isValid();
response.getExpiresIn(); // Value in seconds



LOCALHOST TEST URL

http://localhost:8080/oxauth/authorize?response_type=code&redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb%3ffoo%3dbar&state=xyz&client_id=@!1111!0008!FF81!2D39
http://localhost:8080/oxauth/authorize.seam?response_type=code&client_id=06fe985f-4111-41cf-a16d-434ff48f92a2.localhost&redirect_uri=http%3A%2F%2Flocalhost%2FoxServer&state=xyz



REGISTRATION

$ cat clients.ldif
dn: ou=clients,o=gluu
objectClass: organizationalUnit
objectClass: top
ou: clients

$ ldapmodify --defaultAdd --port 1389 --bindDN 'cn=directory manager' --bindPassword secret --filename clients.ldif




$ cat addClient.ldif
dn: inum=@!1111!0000!6216!CCE6,ou=clients,o=gluu
displayName: oxAuth test app
inum: @!1111!0000!6216!CCE6
objectClass: oxAuthClient
objectClass: top
oxAuthAppType: web
oxAuthClientExpirationDate: 20120120152419.312Z
oxAuthRedirectURI: https://client.example.com/cb
oxAuthRedirectURI: https://client.example.com/cb1
oxAuthRedirectURI: https://client.example.com/cb2
oxAuthScope: openid
oxAuthScope: profile
oxAuthScope: address
oxAuthScope: email
oxAuthClientSecret: 607ae292-c8fe-486e-87d8-c28f84f8c0bd

$ ldapmodify --defaultAdd --port 1389 --bindDN 'cn=directory manager' --bindPassword secret --filename addClient.ldif



oxTrust
client_id: @!1111!0008!C2EB!75F1

oxPlus
client_id: @!1111!0008!2A19!9A70

oxServer
client_id: @!1111!0008!7119!0560

Gluu IDP
client_id: @!1111!0008!45C0!BE6E

Test
client_id: @!1111!0008!FF81!2D39

oxModel
client_id: @!1111!0008!92C1!D277

oxGraph
client_id: @!1111!0008!0336!1008

oxTestTool
client_id: @!1111!0008!A64C!475C

client_id: @!1111!0008!31FD!E7E7

client_id: @!1111!0008!2D7F!97C2