trackr-api-documentation/security.html at gh-pages · techdev-solutions/trackr-api-documentation · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
<!DOCTYPE html><html><head><meta http-equiv="Content-Type" content="text/html" charset="utf-8"><link rel="stylesheet" href="http://yui.yahooapis.com/pure/0.5.0/pure-min.css"><link rel="stylesheet" href="http://yui.yahooapis.com/pure/0.5.0/grids-responsive-min.css"><link rel="stylesheet" href="css/trackr.css"><link href="http://fonts.googleapis.com/css?family=Lobster" rel="stylesheet" type="text/css"><meta name="viewport" content="width=device-width, initial-scale=1"><title>trackr API documentation</title></head><body><div id="menu"><header><div>trackr</div></header><!-- set path to ../ for pages in a subfolder--><div class="pure-menu pure-menu-open"><a href="getting_started.html" class="pure-menu-heading">Getting started</a><ul><li><a href="starting_server.html">Starting the application</a></li><li class="pure-menu-selected"><a href="security.html">Accessing the application</a></li></ul><a class="pure-menu-heading">Application internals</a><ul><li><a href="scheduled_jobs.html">Scheduled jobs</a></li></ul><a href="api_overview.html" class="pure-menu-heading">API documentation</a><ul><li><a href="api/address_book.html">/address_book</a></li><li><a href="api/addresses.html">/addresses</a></li><li><a href="api/authorities.html">/authorities</a></li><li><a href="api/billableTimes.html">/billableTimes</a></li><li><a href="api/companies.html">/companies</a></li><li><a href="api/contactPersons.html">/contactPersons</a></li><li><a href="api/credentials.html">/credentials</a></li><li><a href="api/employees.html">/employees</a></li><li><a href="api/federalStates.html">/federalStates</a></li><li><a href="api/holidays.html">/holidays</a></li><li><a href="api/invoices.html">/invoices</a></li><li><a href="api/principal.html">/principal</a></li><li><a href="api/projects.html">/projects</a></li><li><a href="api/sickDays.html">/sickDays</a></li><li><a href="api/translations.html">/translations</a></li><li><a href="api/travelExpenseReports.html">/travelExpenseReports</a></li><li><a href="api/travelExpenseReportComments.html">/travelExpenseReportComments</a></li><li><a href="api/travelExpenses.html">/travelExpenses</a></li><li><a href="api/vacationRequests.html">/vacationRequests</a></li><li><a href="api/workTimes.html">/workTimes</a></li></ul></div></div><div id="content"><header><div>API Documentation</div></header><div class="pure-g"><div class="pure-u-1 pure-u-lg-1-24"></div><div class="pure-u-1 pure-u-lg-5-6"><h1>Security - how to access the API when it is running</h1><p>There are several ways to do this.</p><h2>Get an access token via the predefined client</h2><p>Trackr uses OAuth so you need an access token to access the API.</p><p>Two possibilities to get an access token. Choose one and continue below.</p><ol><li>Use the admin account. This feature might be removed in future releases.</li><li>You need a valid account in the database an use Google Open ID login. If you have the dev profile active, edit the file src/main/resources/import.sql. Choose a credential INSERT (not the admin one, though) and change the mail address to your gmail address.<pre>INSERT INTO credential (id, email, enabled, locale) VALUES (1, 'your.address@gmail.com', true, 'de');</pre><p>If you use the qs or prod profile you need to insert the employee + credential in the database you configured.</p></li></ol><p>If you have chosen your option, start the server and access</p><pre>http://localhost:8080/oauth/authorize?client_id=trackr-page&response_type=token&redirect_uri=http://localhost</pre><p>You will be redirected to http://localhost:8080/login. If your option was 1) then replace /login with /admin and hit enter. Login with admin@techdev.de/techdev. If your option was 2) click "Login mit Google" and choose the account you added in 2).</p><p>Either way you should see the authorize page. Press submit and you should be redirected to</p><pre>http://localhost/#access_token=SOME_TOKEN&token_type=bearer&expires_in=43199&scope=read%20write</pre><p>Copy the SOME_TOKEN value, it's your access token. Now you should be able to access the API like this</p><pre>curl localhost:8080/api/ -H "Authorization: Bearer SOME_TOKEN"
</pre><h2>Disable security alltogether</h2><p><b>Note</b> Some methods of the API don't work without security as they rely on a principal object. They will just throw a NullPointerException when you disable security. If your just interested in the Spring Data REST API, most of it should work.<ol><li>Edit the file de/techdev/trackr/core/SecurityWebApplicationInitializer.java
Comment out the extends and the constructor.<pre>public class SecurityWebApplicationInitializer /*extends AbstractSecurityWebApplicationInitializer*/ {
    public SecurityWebApplicationInitializer() {
        //super(SecurityConfiguration.class, JpaConfiguration.class, MethodSecurityConfiguration.class);
    }
}</pre>This prohibits the Spring Security filter chain to be initalized</li><li>Edit the file de/techdev/trackr/core/ApiWebApplicationInitializer.java
Remove the MethodSecurityConfiguration.class from getServletConfigClasses()
Add JpaConfiguration.class to getRootConfigClasses()<pre>public class ApiWebApplicationInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {
    @Override
    protected Class<?>[] getRootConfigClasses() {
        return new Class<?>[] {JpaConfiguration.class};
    }
        @Override
    protected Class<?>[] getServletConfigClasses() {
        return new Class<?>[] {ApiWebMvcConfiguration.class, /*MethodSecurityConfiguration.class,*/ MailConfiguration.class, ScheduledJobsConfiguration.class};
    }
    //...
}</pre>The MethodSecurityConfiguration has an @Autowired bean that's not present and the JpaConfiguration needs to be loaded since we disabled it with the SecurityWebApplicationInitializer.</li></ol></p><p>Now, when you start the application you should be able to curl the API:</p><pre>curl localhost:8080/api/
</pre><h2>Get an access token with an additional client (advanced)</h2><p><b>Note:</b> Like disabling security, some methods might not work with this approach since you won't have a correct principal.</p><p>The predefined client needs a browser to work and everytime you restart (at least in dev profile) you have to click through all pages again. A client with the client_credentials grant makes this a little easier.</p><p>Edit the file de/techdev/trackr/core/security/OAuth2ServerConfiguration.java and change this method:</p><pre>@Override
public void configure(ClientDetailsServiceConfigurer clients) throws Exception {
    clients.inMemory().withClient("trackr-page")
        .resourceIds(TRACKR_RESOURCE_ID)
        .authorizedGrantTypes("authorization_code", "implicit")
        .authorities("ROLE_CLIENT")
        .scopes("read", "write")
        .redirectUris(trackrPageRedirectUris.split(","))
        .and().withClient("example")
            .resourceIds(TRACKR_RESOURCE_ID)
            .authorizedGrantTypes("client_credentials")
            .authorities("ROLE_ADMIN")
            .scopes("read", "write")
            .secret("example");
}
</pre><p>The lines after withClient("example") are new.</p><p>Now you have an OAuth client with the client_credentials grant and can get an access token like this:</p><pre>curl -u example:example localhost:8080/oauth/token\?grant_type=client_credentials</pre><p>With that token you can access the API like this</p><pre>curl localhost:8080/api/ -H "Authorization: Bearer SOME_TOKEN"</pre></div><div class="pure-u-1 pure-u-lg-3-24"></div></div></div></body></html>