Colleges wishing to use this service will need to contact the TechCenter so that a client Id and secret can be generated. The client Id and secret will be used to authenticate requests to this service. College will need to provide the EPPN domain when requesting credentials.

EPPN Service Information

Service Name	EPPN Lookup Service
Service Version	2.0
Service Description	Lookup EPPN to CCCID mappings used by the CCC Identity Provider Proxy. SwaggerUI Docs: https://profile-eppn.ci.cccmypath.org/eppn/swagger-ui.html#/eppn-controller-v-2
Service Usage	This service is intended for colleges that would like to be able to retrieve the CCCIDs being associated with EPPNs that are routed through the CCC IDP Proxy. Every student that accesses a service through the IDP Proxy must have a CCCID. If the college IDP cannot provide the CCCID, then the IDP Proxy will attempt to map the colleges EPPN to the CCCID. This service provides a way for colleges to read those mappings so that they may potentially be imported back into the colleges SIS. Colleges wishing to use this service will need to contact the TechCenter so that a client Id and secret can be generated. The client Id and secret will be used to authenticate requests to this service. College will need to provide the EPPN domain when requesting credentials. A Java client library is available. The client allows property file configuration of endpoints and authentication. The Java client library will handle lookup up the OpenId token, setting the Authorization header, hitting the REST endpoint and converting data into Java objects. To import the library include the following segment in your pom file: <properties> <ccc.common-identity.version>2.0.0</ccc.common-identity.version> <eppn-service.version>1.1-SNAPSHOT</eppn-service> </properties> <repositories> <repository> <id>nexus-releases</id> <name>CCC Nexus Repo - Release</name> <url>https://nexus.dev.ccctechcenter.org/content/repositories/releases</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </repository> <repository> <id>nexus-snapshots</id> <name>CCC Nexus Repo - Snapshots</name> <url>https://nexus.dev.ccctechcenter.org/content/repositories/snapshots</url> <releases> <enabled>false</enabled> </releases> <snapshots> <enabled>true</enabled> </snapshots> </repository> </repositories> <dependencies> <dependency> <groupId>net.cccnext.services</groupId> <artifactId>eppn-service-client</artifactId> <version>${eppn-service.version}</version> </dependency> <dependency> <groupId>net.cccnext</groupId> <artifactId>common-identity</artifactId> <version>${ccc.common-identity.version}</version> </dependency> </dependencies> To configure the EPPN Service for a spring boot application: @Configuration @PropertySources({ @PropertySource("classpath:defaults.properties"), @PropertySource(value = "file:overrides.properties", ignoreResourceNotFound = true), }) @EnableConfigurationProperties public class Config { @Autowired EppnServerSettings serverSettings; /** * Configure the EPPN service object. EPPN service object provides the following methods: * * Eppn getEppnMapping(String eppn); * Page<Eppn> getNewMappings(); * Page<Eppn> getNewMappings(int page, int pageSize); * Page<Eppn> getMappingsSince(Date d); * * List<BatchStatus<String>> markAsDownloaded(String... eppn); * List<BatchStatus<String>> markAsDownloaded(List<Eppn> eppnList); */ @Bean public IEppnService getEppnService() throws NoSuchAlgorithmException, KeyStoreException, KeyManagementException { EppnV2Service svc = new EppnV2Service(); svc.setRestOperations(getRestTemplate()); svc.setServerSettings(serverSettings); return svc; } @Bean public RestOperations getRestTemplate() throws KeyStoreException, NoSuchAlgorithmException, KeyManagementException { ServiceAccountManager manager = getServiceAccountManager(); CCCRestTemplate template = new CCCRestTemplate(); template.setJwtGetter(manager); return template; } @Bean public ServiceAccountManager getServiceAccountManager() { return new ServiceAccountManager(serverSettings.getBaseTokenUrl(), serverSettings.getClientId(), serverSettings.getClientSecret()); } @Bean public static PropertySourcesPlaceholderConfigurer propertyConfig() { return new PropertySourcesPlaceholderConfigurer(); } } Config file: `eppn-service.server=profile-eppn.cccmypath.org eppn-service.contextPath=/eppn eppn-service.secure=true eppn-service.allowInsecureHttps=false eppn-service.baseTokenUrl=https://login.cccmypath.org/f eppn-service.clientId=NEEDS_OVERRIDE eppn-service.clientSecret=NEEDS_OVERRIDE`
Release Notes
Valid Period	4/26/2017 -
Service Location	CI: https://profile-eppn.ci.cccmypath.org/eppn/* TEST: https://profile-eppn.test.cccmypath.org/eppn/* PILOT: https://profile-eppn.pilot.cccmypath.org/eppn/* PROD: https://profile-eppn.cccmypath.org/eppn/*
Methods	Get EPPN – lookup a single EPPN → CCCID mapping Mappings Created Since – find all EPPN → CCCID mappings created since a specific date Get New Mappings – find all EPPN → CCCID mappings that have not previously been marked as downloaded Mark Mapping as Downloaded – Mark an EPPN → CCCID mapping as downloaded

Service Operation: Get EPPN

Name	/eppn/2.0/eppn-mappings/{EPPN}
Description	Lookup the mapping for a single EPPN
HTTP Method	GET
Preconditions	Caller must have have a valid OpenID token Caller clientId must match the domain of the requested EPPN. (ie. If the eppn is jdoe@santarosa.edu, the clientId for the caller must be "santarosa.edu")
Post-conditions
Message Exchange Pattern	Request is received EPPN mapping is looked up Mapping is returned

Inputs

EPPN Parameters

Description	The College EPPN to lookup
Type	Path Parameter
Required	Yes
Default	N/A

Output

Description	EPPN Mapping JSON
Data Type	`{ "authSource": "string", "cccId": "string", "createTime": "2017-03-24T22:47:08.089Z", "downloaded": boolean, "eppn": "string" }`

Faults

Unauthorized

Description	Calling service has not been authenticated
Http Status Code	401
Additional Information

Forbidden

Description

Calling service has been authenticated, but does not have permissions to make this request

HTTP Status Code

403

Additional Information

Service Operation: Get Mappings Created Since

Name	/eppn/2.0/eppn-mappings/since/{DATE}
Description	Lookup all mappings that have an authsource matching the clientId of the caller that have been entered since DATE.
HTTP Method	GET
Preconditions	Caller must have have a valid OpenID token DATE Must be in YYYY-MM-DD format
Post-conditions
Message Exchange Pattern	Request is received EPPN mappings are looked up List of mappings is returned

Input

Date Parameters

Description	Lookup all EPPN mappings for the given college since DATE (inclusive). Date must be in YYYY-MM-DD format.
Type	Path Parameter
Required	Yes
Default	N/A

pageSize Parameters

Description	Maximum number of mappings to return per request
Type	Query Parameter
Required	No
Default	1000

pageNumber Parameters

Description	0 based index of the page of records to retrieve
Type	Query Parameter
Required	No
Default	0

Output

Description	A page of EPPN mappings
Data Type	`{ "data": [ { "authSource": "string", "cccId": "string", "createTime": "2017-03-24T22:58:08.904Z", "downloaded": boolean, "eppn": "string" } ], "pageNumber": integer, "pageSize": integer, "totalElements": integer }`

Faults

Unauthorized

Description	Calling service has not been authenticated
Http Status Code	401
Additional Information

Forbidden

Description	Calling service has been authenticated, but does not have permissions to make this request
HTTP Status Code	403
Additional Information

Service Operation: Get New Mappings

Name	/eppn/2.0/eppn-mappings/new-mappings
Description	Lookup all mappings that have an authsource matching the clientId of the caller that have not previously been marked as downloaded (See: Service Operation: Mark downloaded)
HTTP Method	GET
Preconditions	Caller must have have a valid OpenID token
Post-conditions
Message Exchange Pattern	Request is received EPPN mappings are looked up List of mappings is returned

Input

pageSize Parameters

Description	Maximum number of mappings to return per request
Type	Query Parameter
Required	No
Default	1000

pageNumber Parameters

Description	0 based index of the page of records to retrieve
Type	Query Parameter
Required	No
Default	0

Output

Description	A page of EPPN mappings
Data Type	`{ "data": [ { "authSource": "string", "cccId": "string", "createTime": "2017-03-24T22:58:08.904Z", "downloaded": boolean, "eppn": "string" } ], "pageNumber": integer, "pageSize": integer, "totalElements": integer }`

Faults

Unauthorized

Description	Calling service has not been authenticated
Http Status Code	401
Additional Information

Forbidden

Description	Calling service has been authenticated, but does not have permissions to make this request
HTTP Status Code	403
Additional Information

Service Operation: Mark Downloaded

Name	/eppn/2.0/eppn-mappings/batch/downloaded
Description	Mark a set of EPPN mappings as downloaded. This operation affects the data returned from the /eppn/eppn-mappings/new-mappings request.
HTTP Method	POST
Preconditions	Caller must have have a valid OpenID token
Post-conditions
Message Exchange Pattern	Request is received EPPN mappings are looked up List of mappings is returned

Input

eppnVals Parameters

Description	An array of EPPN mappings to mark as having been downloaded.
Type	Body Content
Required	Yes
Default	N/A
Example	["jdoe1@santarosa.edu", "jdoe2@santarosa.com"]

Output

Description	An array of status objects. The array will consist of a single record for each EPPN listed in the request. The "status" field be set to either "Updated" or "Error"
Data Type	`[ { "entityId": "string" // eppn value "status": "string" // will be either "Updated" or "Error" } ]`

Faults

Unauthorized

Description	Calling service has not been authenticated
Http Status Code	401
Additional Information

Forbidden

Description	Calling service has been authenticated, but does not have permissions to make this request
HTTP Status Code	403
Additional Information